In our last Retrofit post we've given you an introduction to converters. In this blog post, we want to dive deeper into the most common format: JSON. After demonstrating the integration of the Gson converter, we'll also show you how to customize Gson's mapping rules.
If you prefer to catch up with other Retrofit topics first, give our outline a look:
Retrofit Series Overview
- Getting Started and Creating an Android Client
- Basics of API Description
- Creating a Sustainable Android Client
- URL Handling, Resolution and Parsing
- How to Change API Base Url at Runtime
- Multiple Server Environments (Develop, Staging, Production)
- Share OkHttp Client and Converters between Retrofit Instances
- Upgrade Guide from 1.9
- Beyond Android: Retrofit for Java Projects
- How to use OkHttp 3 with Retrofit 1
- Synchronous and Asynchronous Requests
- Send Objects in Request Body
- Add Custom Request Header
- Manage Request Headers in OkHttp Interceptor
- Dynamic Request Headers with @HeaderMap
- Multiple Query Parameters of Same Name
- Optional Query Parameters
- Send Data Form-Urlencoded
- Send Data Form-Urlencoded Using FieldMap
- How to Add Query Parameters to Every Request
- Add Multiple Query Parameter With QueryMap
- How to Use Dynamic Urls for Requests
- Constant, Default and Logic Values for POST and PUT Requests
- Cancel Requests
- Reuse and Analyze Requests
- Optional Path Parameters
- How to Send Plain Text Request Body
- Customize Network Timeouts
- How to Trust Unsafe SSL certificates (Self-signed, Expired)
- Dynamic Endpoint-Dependent Interceptor Actions
- How to Update Objects on the Server (PUT vs. PATCH)
- How to Delete Objects on the Server
- Introduction to (Multiple) Converters
- Adding & Customizing the Gson Converter
- Implementing Custom Converters
- How to Integrate XML Converter
- Access Mapped Objects and Raw Response Payload
- Supporting JSON and XML Responses Concurrently
- Handling of Empty Server Responses with Custom Converter
- Send JSON Requests and Receive XML Responses (or vice versa)
- Unwrapping Envelope Responses with Custom Converter
- Wrapping Requests in Envelope with Custom Converter
- Define a Custom Response Converter
Integrate a JSON Converter
A common representation of the data received from the server is the JavaScript object notation: JSON. HTTP’s response body contains any information and Retrofit parses the data and maps it into a defined Java class. This process can be kind of tricky, especially when working with custom formatted dates, nested objects wrapped in lists, and so on …
As we’ve mentioned in our Upgrade Guide, Retrofit doesn’t ship with an integrated JSON converter anymore. We need to include the converter manually. For those of you, who already worked with Retrofit 2, you’ve probably edited your build.gradle. In case you haven’t done that yet, it’s the time to do it now:
dependencies {
// Retrofit & OkHttp
compile 'com.squareup.retrofit2:retrofit:2.5.0'
// JSON Converter
compile 'com.squareup.retrofit2:converter-gson:2.5.0'
}
Google’s Gson is a very popular JSON converter. Almost every real-world JSON mapping can be done with the help of Gson. Once you’ve added the Gradle dependency to your project you’ve to activate it on your Retrofit instance. Only then Retrofit will consider using the converter.
Retrofit retrofit = new Retrofit.Builder()
.baseUrl("https://api.github.com")
.addConverterFactory(GsonConverterFactory.create())
.build();
GitHubService service = retrofit.create(GitHubService.class);
The converter dependency provides a GsonConverterFactory class. Call the created instance of that class (done via create()) to your Retrofit instance with the method addConverterFactory(). After you’ve added the converter to Retrofit, it’ll automatically take care of mapping the JSON data to your Java objects, as you’ve seen in the previous blog post. Of course, this works for both directions: sending and receiving data.
The advantage of Gson is that it usually needs no setup in your Java classes. Nevertheless, there are notations for some edge cases. If your app requires Gson to do something special, head over to the Gson project to look up the details.
Customize Your Gson Configuration
We want you to know that Gson has plenty of configuration options. Please go through the official User Guide, if you want to get an overview over all the options.
The good news is that Retrofit makes it very easy to customize Gson. You don’t even need to implement your own custom converter, which we’ll look at later in another blog post. In the previous section, we’ve explained that you can add the Gson converter like this:
Retrofit retrofit = new Retrofit.Builder()
.baseUrl("https://api.github.com")
.addConverterFactory(GsonConverterFactory.create())
.build();
We didn’t tell you, that you can pass a Gson instance to the GsonConverterFactory.create() method. Here’s an example with various Gson configurations:
Gson gson = new GsonBuilder()
.registerTypeAdapter(Id.class, new IdTypeAdapter())
.enableComplexMapKeySerialization()
.serializeNulls()
.setDateFormat(DateFormat.LONG)
.setFieldNamingPolicy(FieldNamingPolicy.UPPER_CAMEL_CASE)
.setPrettyPrinting()
.setVersion(1.0)
.create();
Retrofit retrofit = new Retrofit.Builder()
.baseUrl("https://api.github.com")
.addConverterFactory(GsonConverterFactory.create(gson))
.build();
If you pass a Gson instance to the converter factory, Retrofit will respect all of your configurations. This makes it very easy to do the fine-tuning of your JSON mapping with Gson, while keeping the actual code changes to a minimum.
Outlook
In this blog post, you've learned how to add Gson as a JSON converter to Retrofit 2. Additionally, you've seen how you can utilize the wide array of options of Gson. Retrofit makes it very easy to customize the Gson mapping rules.
