Retrofit 2 – Query and Path parameters example

Learn to perform requests with single, multiple and even optional query parameters and path parameters using @Query and @Path annotations in Retrofit 2.

1. Query parameters

Retrofit uses @Query annotation to define query parameters for requests. Query parameters are defined before method parameters. In annotation, we pass the query parameter name which will be appended in the URL.

1.1. Single or multiple query parameters

Use as many @Query annotations as many parameters we want to send.

https://<DOMAIN>/api/users?page=2&per_page=10
@GET("/api/users")
public Call<UsersApiResponse> getUsers(@Query("per_page") int pageSize, 
					@Query("page") int currentPage);

Pass the value of parameters when invoking the actual API call.

1.2. Multiple query parameters with same name

Let’s suppose we want to send multiple parameters which all have same name e.g. userId. It’s very uncommon scenario – still this can help we come across this requirement.

https://<DOMAIN>/api/users?userId=1&userId=2&userId=3

On server, it will be recieved as userId = [1,2,3].

@GET("/api/users")
public Call<UsersApiResponse> getUsers(@Query("userId") List<Integer> ids);

1.3. Encoded query parameter

@Query annotation takes an attribute i.e. encoded. It is of boolean type and takes either true or false.

It specifies whether the argument value to the annotated method parameter is already URL encoded or not. Based on it’s value, URL encoding is performed on passed value. If value is passes as already URL encoded, no default URL encoding takes place.

By default, passed values are converted to encoded string.

1.4. Optional query parameters

Depending on the API design, in above examples, query parameter might be optional. In case we don’t want to pass the parameter with the request, we should just pass null as the value.

Retrofit skips null parameters and ignores them while creating the request.

We cannot pass 'null' to primitive types. So it is always recommended to use wrapper classes as parameter types.

E.g. Call to service.getUsers(null, null) will result in 'https://DOMAIN/api/users'.

2. Path parameters

Path parameters in Retrofit 2 are denoted with @Path annotation. They also come before method parameters. They are named replacement in a URL path segment.

Path parameters may not be null.

Values passed in @Path annotations modified and made URL encoded before full API path resolution.

2.1. Simple path parameter

An example to use @Path parameters in Retrofit 2.

@GET("/api/users/{id}")
public Call<UserApiResponse> getUser(@Path("id") Long id);

Calling above API with service.getUser(1) yields ‘/api/users/1’.

2.2. Encoded path parameter

@Path annotation takes an attribute i.e. encoded. It is of boolean type and takes either true or false.

It specifies whether the argument value to the annotated method parameter is already URL encoded or not. Based on it’s value, URL encoding is performed on passed value. If value is passes as already URL encoded, no default URL encoding takes place.

By default, passed path parameters are converted to encoded string.

2.2.1. encoded = true
@GET("/user/{name}")
Call<ResponseBody> getUserByName(@Path(value="name") String name);

//OR - encoded is default 'true'

@GET("/user/{name}")
Call<ResponseBody> getUserByName(@Path(value="name", encoded=true) String name);

service.getUserByName("John+Doe") will be resolved to '/user/John%2BDoe'.

2.2.2. encoded = false
@GET("/user/{name}")
Call<ResponseBody> getUserByName(@Path(value="name", encoded=false) String name);

service.getUserByName("John+Doe") will be resolved to '/user/John+Doe'.

3. Conclusion

In this Retrofit tutorial, we’ve seen how we can use single, multiple and optional query parameters. We also learned to use path parameters.

Drop me your questions in comments.

Happy Learning !!

References:

Retrofit Query annotation
Retrofit Path annotation

Was this post helpful?

Join 7000+ Awesome Developers

Get the latest updates from industry, awesome resources, blog updates and much more.

* We do not spam !!

2 thoughts on “Retrofit 2 – Query and Path parameters example”

  1. what is the difference between @Query and @Path ? and when we have to use @Path (when if we don’t wan to get null parameter ?) and when we have to use @Query parameter (if user can be null parameter ?) ? Am I right ?

    Reply
    • URL => Uniform Resource Locator
      Consists of the Base URL => Actual Endpoint where we want to query i.e. the Server IP.
      Segments OR Path => The location on the server where we want to query i.e. the Ultimate Resource. such as File or Database
      Query => The filter on the resource to select specific entries or resource values

      Such as
      http://www.google.com/api/users?top=10&startsWith=a

      Base URL => http://www.google.com
      Path = api/users
      Query 1: top=10 => Get me first 10 results from users database
      Query 2: startsWith = a => Get me lists of users start with “a”

      Reply

Leave a Comment

HowToDoInJava

A blog about Java and related technologies, the best practices, algorithms, and interview questions.