Retrofit 2 — Introduction to (Multiple) Converters

In the past few days and weeks we've shown you a lot of details on how to work with Retrofit 2. In this and the next blog post we'll show you a significant component of Retrofit: converters.

If converters don't take your breath away, you might find a more interesting topic in our extensive list of Retrofit topics:

Retrofit Series Overview

Integrating Standard Converters

In order to make the communication work between the Android client and the server, they need to agree on a common data representation format. Over the years developers have introduced various formats with each their own purpose, advantages and disadvantages. What all formats have in common is that you need to map Java objects into the standard format. In Retrofit 2, this task of mapping between Java objects and the standard format is done by converters. Converters can support two directions here: from Java object to standard format (requests) and vice versa: from the standard format to Java objects (responses).

Since there are so many formats and libraries to support them, the Retrofit creators provide a list of converters. We can’t go through every single one of them, so we just give you an overview. The retrofit-converters directory lists all official response converter implementations:


Gson is for JSON mapping and can be added with the following dependency:

compile 'com.squareup.retrofit2:converter-gson:2.5.0'  


SimpleXML is for XML mapping. You’ll need the following line for your build.gradle:

compile 'com.squareup.retrofit2:converter-simplexml:2.5.0'  


Jackson is an alternative to Gson and claims to be faster in mapping JSON data. The setup offers you a lot more customization and might be worth a look. You can add it with:

compile 'com.squareup.retrofit2:converter-jackson:2.5.0'  


Moshi is another alternative to Gson. It’s created by the developers of Retrofit. Moshi is based on Gson, but differentiates itself with some simplifications. If you want to give this young new player on the market a try, add it with:

compile 'com.squareup.retrofit2:converter-moshi:2.5.0'  


Protobuf is build for the format Protocol Buffers, which is a new mechanism of serializing structured data. Protocol Buffers is a new generation and comes with a lot of upside. If your API already utilizes it, you can quickly add support on the app side with:

compile 'com.squareup.retrofit2:converter-protobuf:2.5.0'  


Wire is also for the Protocol Buffers format. It’s developed by the creators of Retrofit and brings their vision of code to this converter. If you’re interested, take a look by adding the dependency:

compile 'com.squareup.retrofit2:converter-wire:2.5.0'  


Finally, if you’re overwhelmed by all these complex data structures and just want to map the basic Java primitives, you can use Scalars:

compile 'com.squareup.retrofit2:converter-scalars:2.5.0'  

Retrofit is open and allows other converters. For example, we’ll look into developing our own custom converter in a future blog post. Of course, you can provide your converter to the developer community and expand the list of available converters. One excellent third-party library is this converter, which adds support for the Logan Square JSON serialization library. While Retrofit makes it very easy to support multiple data formats, there are a few things you need to keep in mind in order to preserve everything working.

Dealing with Multiple Converters

Retrofit accepts various structured data formats by outsourcing the conversion of those to independent converters. These converters usually only have one specific purpose. For example, Gson deals with the JSON format, while SimpleXML transforms XML data. Retrofit makes it easy by allowing the developer to call addConverterFactory() on the Retrofit builder multiple times. As long as the converters are conflict free, e.g. Gson vs. SimpleXML, there won’t be any issues. But what happens if you add two converters, which do more or less the same job, e.g. Moshi vs. Gson?

Retrofit has a simple way of dealing with this issue. First of all, it checks with every converter if it’s able to deal with this specific data type. If the passed converter cannot understand some data, it won’t be considered for the request (but will be asked again for the next request). The order of checks is done by first-come first-serve. That means the first converter you pass to Retrofit with addConverterFactory() will be checked first. If the first converter accepts the challenge, the rest of the list will not be asked.

Effectively, this means that you need to be very careful when adding the converters! Make sure you **specify the special-purpose converters with limited abilities first and general converters (like Gson) last.


In this blog post, you've learned what Retrofit uses converters for mapping data for various standard formats to and from Java objects. You've also seen an overview of all provided standard converters. Finally, you understand how to deal with multiple formats.

In the next blog post, we'll go deeper into the JSON converter and show you how to customize the Gson mapping.

Explore the Library

Find interesting tutorials and solutions for your problems.