Many mobile apps need exchange data with a server (mostly by HTTP protocol). It could be realized by REST API. What is REST I shortly introduced here. Retrofit is a REST client for Android (or just Java) developed by Square.
Of course, you can create the connection with the server without external libraries, but it will be consumed more time and required more code that you have to maintain. To simply this process you should use the HTTP client such as Volley or Retrofit. In this article, I briefly show the second solution.
Shortly how it works?
Retrofit use the HTTP client (OkHttp) that care about connection and download or upload data as a JSON or XML from/to API. JSON or XML is mapped into Plain Old Java Object (POJO). Here I will focus on JSON format. To serialize and deserialize JSON data Retrofit could use a one from few available library (Jackson, Moshi, Protobuf, Wire, Simple Framework), but the most popular is a Gson. Gson library requires some things that you have to do, but here also is a perfect solution. Firstly we must create POJO objects. I highly recommended use jsonschema2pojo. This is a site, where you can prepare your objects in a simple way. Now to take your prepared classes you only have to select source type as JSON, set Annotation style to Gson and paste JSON into a textbox. Set up yet package where a model will be placed and name your main class and download ready zip. Paste your generated classes to the right place in your project. The first step is done.
Next is time to define an interface which could be called contract what will be realized. To use concrete action you must use HTTP verbs as an annotation and create a function that will return Call object with the type of the expected result. You can add additional parameters to your query or complete missing elements your path. For post request available is annotation @Body.
To finish your API consumption you need to add last base element that is retrofit instance creation. It is available by builder pattern. You can add base URL that is our endpoint (shouldn’t be modified), add converter factory (in our case is GsonConverterFactory) and for example OkHttp client to authentication (another way to provide authentication is header manipulation).
The last step is to bring this all creating your interface. An important feature is consuming API asynchronously. This is realized by method enqueue(). If you want to execute your request synchronously you should use execute(). That’s all. Our connection is ready!
Note Retrofit can also be extended by adapters. This is important if we want to use other libraries as RxJava, Java8 or Guava.
Take a look on RxJava example. It is possible by adding the adapter to the retrofit instance. To execute request asynchronously you should set schedulers to your adapter. Now service returns Observable with our object that we can subscribe. This is the very helpful library.
Summary if you need consume API you should use REST client as a Retrofit and I think you will be satisfied.
You need three main steps:
- create a Java objects as your model
- create the interface with our functions and parameters described by annotations
- create and configure the retrofit instance and execute your request