This tutorial is going to show how to post JSON with Retrofit, a type-safe HTTP client for Android and Java.
1. Library Dependency
We’re going to use Retrofit 2.3.0 for all examples presented in this tutorial. And To use Retrofit with Maven, we will need to include the following dependency into our pom.xml file:
1 2 3 4 5 |
<dependency> <groupId>com.squareup.retrofit2</groupId> <artifactId>retrofit</artifactId> <version>2.3.0</version> </dependency> |
To use Retrofit with Gradle:
1 |
compile 'com.squareup.retrofit2:retrofit:2.3.0' |
2. Rest API
In this tutorial, we will use Retrofit to post Json to a Rest API with the following information:
URL to create a resource (book)
1 |
POST http://localhost:8080/v1/books |
Input
Name | Type |
name | the name of the book |
author | the author of the book |
1 2 3 4 |
{ "name": "Java How To Program", "author": "Paul Deitel" } |
1 2 3 4 5 |
{ "id": 5 "name": "Java How To Program", "author": "Paul Deitel" } |
3. Posting JSON With Retrofit
Basically, to post JSON with Retrofit, we will need the following steps:
- To define a POJO class to represent the JSON that we want to post to the Rest API with Retrofit, or we can simply use a Map with its keys are the field names and values are the field values.
- When we use the above POJO object as a service method parameter, we annotate it with a @Body annotation to imply that we want to directly control the request body of a POST/PUT request. The object will be serialized using the Retrofit instance Converter and the result will be set directly as the request body.
Next, we will get through the first way to post JSON with Retrofit: to define a POJO class.
3.1. Defining A POJO Class
3.1.1. POJO Class
Let’s define a POJO class called Book to represent the request body:
1 2 3 4 5 6 7 8 9 10 11 |
public class Book { private Long id; private String name; private String author; public Book() { } // getters and setters } |
3.1.2. Defining A Service Interface
Next, we will need to define a service interface which contains all the methods we need to call/invoke from the Rest API:
1 2 3 4 5 |
public interface BookResource { @POST("books") Call<Book> createBook(@Body Book book); } |
Notice that we annotated the parameter with @Body annotation.
3.1.3. Posting The POJO Object.
Finally, let’s see how we post the Json with Retfofit:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 |
@Test public void testPostJsonByPojo() throws IOException { //create an instance of Retrofit Retrofit retrofit = new Retrofit.Builder() .baseUrl("http://localhost:8080/v1/") .addConverterFactory(GsonConverterFactory.create()) .build(); //create an instance of the BookResource interface BookResource bookResource = retrofit.create(BookResource.class); //create a Book object Book book = new Book(1l, "Java How To Program", "Paul Deitel"); // send the Book to the Rest API Call<Book> call = bookResource.createBook(book); Response<Book> response = call.execute(); assertTrue(response.isSuccessful()); } |
3.2. Using A Map (HashMap) To Represent The JSON
Instead of defining a POJO class to represent the JSON, we can use a Map to represent the JSON we want to post with Retrofit, then use @Body annotation to instruct Retrofit to serialize the Map into JSON before sending to the Rest API.
3.2.1. Defining A Service Interface
Let’s define another method called updateBook in the above service interface as follows:
1 2 3 4 5 6 7 8 9 10 |
public interface BookResource { @POST("books") Call<Book> createBook(@Body Book book); @POST("books") Call<Book> updateBook(@Body Map<String, Object> body); } |
Notice that the parameter of the method is an java.util.Map.
3.2.2. Posting The Map
Let’s see how we create the Map and post it in the following example:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
@Test public void testPostJsonByMap() throws IOException { Retrofit retrofit = new Retrofit.Builder() .baseUrl("http://localhost:8080/v1/") .addConverterFactory(GsonConverterFactory.create()) .build(); BookResource bookResource = retrofit.create(BookResource.class); Map<String, Object> bookMap = new HashMap<>(); bookMap.put("name", "To Kill a Mockingbird"); bookMap.put("author", "Harper Lee"); Call<Book> call = bookResource.updateBook(bookMap); Response<Book> response = call.execute(); assertTrue(response.isSuccessful()); } |
After creating the Retrofit and service interface objects, we create a HashMap to represent the Json and then post the map with Retrofit.
4. Conclusions
The tutorial has illustrated how to post JSON with Retrofit by either defining a POJO class or using a Map to represent the JSON, then annotate those with the @Body annotation which instructs Retrofit to serialize those into JSON before making a request to the Rest API. And we can see that defining a POJO class is suitable for all cases that we have fixed JSON schema while the Map is very flexible for the remaining cases.
The source code presented in the tutorial is available on my Github project. And it’s a Maven based project; it’s will be easy to import into IDE such as Eclipse, IntelliJ IDEA, etc.
Below are other related articles for your references:
Java REST Client Example With Retrofit 2