2. Tutorials
  3. Retrofit — Send Data Form-Urlencoded

Retrofit — Send Data Form-Urlencoded

Multiple methods exist to send data to your server. You may already know how to send data within the request body or how to make use of multipart/form-data to upload files using Retrofit. If not and you’re interested, follow the lead :) There’s another type available to send data to an API or server with your request: form-urlencoded. This post shows you how to annotate your service interface and execute form encoded requests using Retrofit.

Retrofit Series Overview

  1. Getting Started and Creating an Android Client
  2. Basics of API Description
  3. Creating a Sustainable Android Client
  4. URL Handling, Resolution and Parsing
  5. How to Change API Base Url at Runtime
  6. Multiple Server Environments (Develop, Staging, Production)
  7. Share OkHttp Client and Converters between Retrofit Instances
  8. Upgrade Guide from 1.9
  9. Beyond Android: Retrofit for Java Projects
  10. How to use OkHttp 3 with Retrofit 1
  1. Synchronous and Asynchronous Requests
  2. Send Objects in Request Body
  3. Add Custom Request Header
  4. Manage Request Headers in OkHttp Interceptor
  5. Dynamic Request Headers with @HeaderMap
  6. Multiple Query Parameters of Same Name
  7. Optional Query Parameters
  8. Send Data Form-Urlencoded
  9. Send Data Form-Urlencoded Using FieldMap
  10. How to Add Query Parameters to Every Request
  11. Add Multiple Query Parameter With QueryMap
  12. How to Use Dynamic Urls for Requests
  13. Constant, Default and Logic Values for POST and PUT Requests
  14. Cancel Requests
  15. Reuse and Analyze Requests
  16. Optional Path Parameters
  17. How to Send Plain Text Request Body
  18. Customize Network Timeouts
  19. How to Trust Unsafe SSL certificates (Self-signed, Expired)
  20. Dynamic Endpoint-Dependent Interceptor Actions
  21. How to Update Objects on the Server (PUT vs. PATCH)
  22. How to Delete Objects on the Server
  1. Ignore Response Payload with Call<Void>
  2. Receive Plain-String Responses
  3. Crawl HTML Responses with jspoon (Wikipedia Example)
  4. Loading Data into RecyclerView and CardView
  1. Introduction to (Multiple) Converters
  2. Adding & Customizing the Gson Converter
  3. Implementing Custom Converters
  4. How to Integrate XML Converter
  5. Access Mapped Objects and Raw Response Payload
  6. Supporting JSON and XML Responses Concurrently
  7. Handling of Empty Server Responses with Custom Converter
  8. Send JSON Requests and Receive XML Responses (or vice versa)
  9. Unwrapping Envelope Responses with Custom Converter
  10. Wrapping Requests in Envelope with Custom Converter
  11. Define a Custom Response Converter
  1. Simple Error Handling
  2. Error Handling for Synchronous Requests
  3. Catch Server Errors Globally with Response Interceptor
  4. How to Detect Network and Conversion Errors in onFailure
  1. Log Requests and Responses
  2. Enable Logging for Development Builds Only
  3. Log Network Traffic with Stetho and Chrome Developer Tools
  4. Using the Log Level to Debug Requests
  5. Analyze Network Traffic with Android Studio Profiler
  6. Debug and Compare Requests with RequestBin
  1. Introduction to Call Adapters
  2. Custom Call Adapter to Separate OnResponse Callback
  3. How to Integrate RxJava 1.x Call Adapter
  4. How to Integrate RxJava 2.x Call Adapter
  5. How to Integrate Guava Call Adapter
  6. Custom Call Adapter to Separate Network and Gson Errors
  1. Pagination Using Query Parameter
  2. Pagination Using Link Header and Dynamic Urls (Like GitHub)
  3. Pagination Using Range Header Fields (Like Heroku)
  1. How to Upload Files to Server
  2. How to Upload Multiple Files to Server
  3. How to Upload a Dynamic Amount of Files to Server
  4. Upload Files with Progress
  5. Passing Multiple Parts Along a File with @PartMap
  6. How to Download Files from Server
  7. Download Files with Progress Updates
  8. How to Upload Files to Server
  1. Basic Authentication on Android
  2. Token Authentication on Android
  3. OAuth on Android
  4. Hawk Authentication on Android
  5. How to Refresh an Access Token
  1. Activate Response Caching (Etag, Last-Modified)
  2. Check Response Origin (Network, Cache, or Both)
  3. Force Server Cache Support with Response Interceptor
  4. Support App Offline Mode by Accessing Response Caches
  5. Analyze Cache Files
  1. Basics of Mocking Server Responses
  2. Customizing Network Behavior of Mocked Server Responses
  3. Mock APIs with JsonServer
  1. Callbacks
  2. Annotations
  3. Fluent Interface with Builders

Form Encoded Requests

Performing form-urlencoded requests using Retrofit is sort of straight forward. It’s just another Retrofit annotation, which will adjust the proper mime type of your request automatically to application/x-www-form-urlencoded. The following interface definitions for Retrofit 1 and 2 will show you how to annotate your service interface for form-encoded requests. We’ll describe the magic behind the curtain below the code snippets :)

Retrofit 2

public interface TaskService {  
    @FormUrlEncoded
    @POST("tasks")
    Call<Task> createTask(@Field("title") String title);
}

Retrofit 1.9

public interface TaskService {  
    @FormUrlEncoded
    @POST("/tasks")
    void createTask(@Field("title") String title, Callback<Task> cb);
}

We’re using the TaskInterface to illustrate the code. The important part is the @FormUrlEncoded annotation. Please be aware of the fact, that you can’t use this annotation for GET requests. Form encoded requests are intended to send data to the server!

Additionally, you need to use the @Field annotation for the parameters which you’re going to send with your request. Place your desired key inside the @Field("key") annotation to define the parameter name. Further, add the type of your value as the method parameter. If you don’t use String, Retrofit will create a string value using Java’s String.valueOf(yourObject) method.

Let’s have a look at an example to illustrate all the theory! Using the following service call

service.createTask("Research Retrofit form encoded requests");

results in the following form encoded request body:

title=Research+Retrofit+form+encoded+requests

Of course, you can have multiple parameters for your request. Just add further @Field annotations with the desired type.

Form Encoded Requests Using an Array of Values

The example above describes the usage of the @Field annotation only for a single value. If you don’t use string as the object type, Retrofit will do the job to parse a string value from the given object.

However, you can pass an array of values using the same key for your form encoded requests.

Retrofit 2

public interface TaskService {  
    @FormUrlEncoded
    @POST("tasks")
    Call<List<Task>> createTasks(@Field("title") List<String> titles);
}

Retrofit 1.9

public interface TaskService {  
    @FormUrlEncoded
    @POST("/tasks")
    void createTasks(@Field("title") List<String> titles, Callback<List<Task>> cb);
}

As you can see, the only difference to the previously described service interface is the list of titles as the parameter. Retrofit will map a given list titles to the respective key title.

Alright, time to touch another example to get an impression of how the final request will look like.

List<String> titles = new ArrayList<>();  
titles.add("Research Retrofit");  
titles.add("Retrofit Form Encoded")

service.createTasks(titles);

results in the following form encoded request body:

title=Research+Retrofit&title=Retrofit+Form+Encoded

Each item within the list of task titles will be mapped to a key-value-pair by Retrofit. The title key will be the same for every pair. The key-value-pairs are separated by an ampersand (&) and the values are separated from their keys by an equal symbol =.

Field Options

The @Field annotation has an option field for encoding:

  • encoded: can be either true or false; default is false

The encoded option defines whether your provided key-value-pair is already url encoded. To specify the encoded option value, you need to pass it within the @Field annotation. The example below illustrates a code examples and sets the encoded option to true.

@Field(value = "title", encoded = true) String title

Form-Urlencoded vs. Query Parameter

When seeing the results for a form encoded request, you may ask yourself "What is the difference between form-urlencoded and query parameters?". In essence: the request type.

  • form-urlencoded: POST
  • query parameter: GET

Use form-urlencoded requests to send data to a server or API. The data is sent within the request body and not as an url parameter.

Query parameters are used when requesting data from an API or server using specific fields or filter.

Outlook

Using form encoded request is a convenient way sending data to an API or backend. There’s no data object required to map the information into JSON representation. We’ve guided you through the annotations required to execute a form encoded request and also showed you how to pass multiple values for the same key with the request url.

Besides that, you can specifically set the encoded option for your values. If you previously weren’t sure about the difference between query parameter and form encoded requests, you now know when to apply the appropriate one.

If you run into questions or problems, find us on Twitter @futurestud_io or in the comment section below.

Enjoy coding & make it rock!

Marcus Pöhls

Marcus is a fullstack JS developer. He’s passionate about the hapi framework for Node.js and loves to build web apps and APIs. Creator of Futureflix and the “learn hapi” learning path.

Explore the Library

Find interesting tutorials and solutions for your problems.

Android

Node.js

Server

Miscellaneous