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

  1. Getting Started and Creating an Android Client
  2. Retrofit 2 — Basics of API Description
  3. Retrofit 2 — Creating a Sustainable Android Client
  4. Synchronous and Asynchronous Requests
  5. Send Objects in Request Body
  6. Add Custom Request Header
  7. Retrofit 2 — Manage Request Headers in OkHttp Interceptor
  8. Retrofit 2 — Dynamic Request Headers with @HeaderMap
  9. Multiple Query Parameters of Same Name
  10. Optional Query Parameters
  11. Using the Log Level to Debug Requests
  12. Retrofit 2 — Log Requests and Responses
  13. Retrofit 2 — Enable Logging for Development Builds Only
  14. How to Upload Files to Server
  15. Retrofit 2 — How to Upload Files to Server
  16. Retrofit 2 — How to Upload Multiple Files to Server
  17. Retrofit 2 — Passing Multiple Parts Along a File with @PartMap
  18. Basic Authentication on Android
  19. Token Authentication on Android
  20. OAuth on Android
  21. Retrofit 2 — Hawk Authentication on Android
  22. How to Refresh an Access Token
  23. Retrofit 2 — Upgrade Guide from 1.9
  24. Retrofit 2 — Simple Error Handling
  25. How to use OkHttp 3 with Retrofit 1
  26. Send Data Form-Urlencoded
  27. Send Data Form-Urlencoded Using FieldMap
  28. Retrofit 2 — How to Add Query Parameters to Every Request
  29. Retrofit 2 — Add Multiple Query Parameter With QueryMap
  30. Retrofit 2 — How to Use Dynamic Urls for Requests
  31. Retrofit 2 — URL Handling, Resolution and Parsing
  32. Retrofit 2 — Constant, Default and Logic Values for POST and PUT Requests
  33. Retrofit 2 — How to Download Files from Server
  34. Retrofit 2 — Cancel Requests
  35. Retrofit 2 — Reuse and Analyze Requests
  36. Retrofit 2 — How to Change API Base Url at Runtime
  37. Optional Path Parameters
  38. Retrofit 2 — How to Send Plain Text Request Body
  39. Retrofit 2 — Pagination Using Query Parameter
  40. Retrofit 2 — Pagination Using Link Header and Dynamic Urls (Like GitHub)
  41. Retrofit 2 — Pagination Using Range Header Fields (Like Heroku)
  42. How to Integrate XML Converter
  43. Define a Custom Response Converter
  44. Retrofit 2 — Introduction to (Multiple) Converters
  45. Retrofit 2 — Adding & Customizing the Gson Converter
  46. Retrofit 2 — Implementing Custom Converters
  47. Retrofit 2 — Basics of Mocking Server Responses
  48. Retrofit 2 — Customizing Network Behavior of Mocked Server Responses (soon)
  49. Java Basics for Retrofit — Callbacks (soon)
  50. Java Basics for Retrofit — Annotations (soon)
  51. Java Basics for Retrofit — Fluent Interface with Builders (soon)

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.1.0'  


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

compile 'com.squareup.retrofit2:converter-simplexml:2.1.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.1.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.1.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.1.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.1.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.1.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.