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: