Retrofit — Optional Query Parameters

The previous post guided you through the options to add custom headers to your requests. Today, we’re diving into the topic on how to use Retrofit to make request parameters optional.

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)

Query Parameters with Retrofit

Retrofit uses annotations to define query parameters for requests. The annotation is defined before method parameters and specifies the request parameter name. The desired value for this parameter is passed during method call. Let's face a concrete example. The code below illustrates a request method which has /tasks as API endpoint url and provides the option to pass a sort parameter for desired sorting.

Retrofit 1.9

public interface TaskService {  
    List<Task> getTasks(@Query("sort") String order);

Retrofit 2

public interface TaskService {  
    Call<List<Task>> getTasks(@Query("sort") String order);

Assuming that your base url to your API is, the request using the TaskService from above and calling the getTasks method results in this request url:

Optional Query Parameters

Depending on the API design, the sort parameter might be optional. In case you don’t want to pass it with the request, just pass null as the value for order during method call.


Retrofit skips null parameters and ignores them while assembling the request. Keep in mind, that you can’t pass null for primitive data types like int, float, long, etc. Instead, use Integer, Float, Long, etc and the compiler won’t be grumpy.

The upcoming example depicts the service definition for the previously mentioned data types.

Retrofit 1.9

public interface TaskService {  
    List<Task> getTasks(
        @Query("sort") String order,
        @Query("page") Integer page);

Retrofit 2

public interface TaskService {  
    Call<List<Task>> getTasks(
        @Query("sort") String order,
        @Query("page") Integer page);

Now you can pass null for either of the defined query parameters order and page when calling the getTasks method.

service.getTasks(null, null);  

Please let us know about any problems you ran into @futurestud_io.

Additional Ressources

Explore the Library

Find interesting tutorials and solutions for your problems.