In this tutorial you'll learn how to define and send data within HTTP request body with Retrofit. Sending data to the server is one of the most fundamental tasks of Retrofit. Luckily, it's super easy.
Don't forget, we have more tutorials from our Retrofit series for you:
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
Send Objects as Request Body
Retrofit offers the ability to pass objects within the request body. Objects can be specified for use as HTTP request body by using the @Body annotation. The functionality of Retrofit’s @Body annotation hasn’t changed in version 2.
Retrofit 2
public interface TaskService {
@POST("/tasks")
Call<Task> createTask(@Body Task task);
}
Retrofit 1.9
public interface TaskService {
@POST("/tasks")
void createTask(@Body Task task, Callback<Task> cb);
}
The defined Retrofit converter (like Gson) will map the defined object to JSON and it will finally sent as the request’s body to your defined server.
Example
Let’s look at a specific example.
public class Task {
private long id;
private String text;
public Task(long id, String text) {
this.id = id;
this.text = text;
}
}
Instantiating a new Task object fills its properties with values for id and text. Further, when passing the object to the service class, the object fields and values will be converted to JSON.
Retrofit 2
Task task = new Task(1, "my task title");
Call<Task> call = taskService.createTask(task);
call.enqueue(new Callback<Task>() {});
Retrofit 1.9
Task task = new Task(1, "my task title");
taskService.createTask(task, new Callback<Task>)() {});
Calling the service method createTask will convert the properties of task into JSON representation. The JSON of task will look like this:
{
"id": 1,
"text": "my task title"
}
Summary
In this tutorial you've seen how simple it is in Retrofit to send Java objects to the server. Of course, in Retrofit 2, you'll also need to configure the converters correctly. We recommend to read the introduction to converters next.
Please get in touch on Twitter @futurestud_io or in the comments below if you run into problems or want more details.
Enjoy coding & make it rock!
