Sending Query and Form Parameters

A request may require additional parameters submitted as a query string or a form-url-encoded string which comprises of a set of key-value pairs. A request definition should specify the keys to be used and the values may be defined as constants or supplied as arguments.

####1. Query Parameters

A query parameter is identified using @QueryParam by supplying the key for the key-value pair. This annotation can only be used on arguments of type CharSequence.

@GET("/repos/sahan/RoboZombie/issues")
List<Issue> getIssues(@QueryParam("state") String state);

...

List<Issue> openIssues = gitHubEndpoint.getIssues("open");

https://api.github.com/repos/sahan/RoboZombie/issues ?state=open

Certain requests may use many query parameters. Although they can be defined individually using @QueryParam, an alternate approach is to use @QueryParams on a Map<CharSequence, CharSequence>. The entries in the Map should be the key-value pairs for the query string.

@GET("/repos/sahan/RoboZombie/issues")
List<Issue> getIssues(@QueryParams Map<String, String> params);

...

Map<String, String> params = new LinkedHashMap<String, String>();
params.put("state", "open");
params.put("page", "1");
params.put("per_page", "8");

List<Issue> openIssues = gitHubEndpoint.getIssues(params);

https://api.github.com/repos/sahan/RoboZombie/issues? state=open & page=1 & per_page=5

####2. Constant Query Parameters

If the same query parameters are passed for each invocation, they can be declared as constants using @QueryParams and @Param.

@GET("/repos/sahan/RoboZombie/issues")
@QueryParams({@Param(name = "state", value = "open"), 
              @Param(name = "per_page", value = "8")})
List<Issue> getOpenIssues(@QueryParam("page") String page);

...

List<Issue> openIssuesPg1 = gitHubEndpoint.getOpenIssues("1");

https://api.github.com/repos/sahan/RoboZombie/issues? state=open & per_page=10 & page=1

####3. Batch Query Parameters

Query strings may contain key-value pairs with the same key but different values. This is common when multiple options are possible for a query parameter, e.g. hobby=reading & hobby=antiquing.

Batch query parameters are identified with @QueryParams on a map of type Map<String, Collection<CharSequence>>.

@GET("/search/issues")
Results searchOpenIssues(@QueryParams Map<String, Object> params);

...

List<String> values = new ArrayList<String>();
values.add("value1");
values.add("value2");
values.add("value3");

Map<String, Object> params = new LinkedHashMap<String, Object>();
params.put("key", values);
params.put("state", "open");

Results results = gitHubEndpoint.searchOpenIssues(params);

https://api.github.com/search/issues? key=value1 & key=value2 & key=value3 & state=open

####4. Form Parameters

Form parameters are sent as x-www-form-urlencoded data within the body of the request. This is essentially a series of key-value pairs similar to that of a query string. Form parameters are identified using @FormParam on arguments of type CharSequence by supplying the key for the key-value pair.

@POST("/emails/send")
void sendEmail(@FormParam("from") String from, @FormParam("to") String to, 
               @FormParam("subject") String subject, @FormParam("text") String text);

...

endpoint.sendEmail("sahan@example.com", "someone@example.com", "Hi", "Knock-Knock");

request-body: from=sahan@example.com & to=someone@example.com & subject=Hi & text=Knock-Knock

Like query parameters, form parameters may be supplied as a map of key-value pairs using @FormParams on a request argument of type Map<CharSequence, CharSequence>.

@POST("/emails/send")
void sendEmail(@FormParams Map<String, String> params);

...

Map<String, String> params = new LinkedHashMap<String, String>();
params.put("from", "sahan@example.com");
params.put("to", "someone@example.com");
params.put("subject", "Hi");
params.put("text", "Knock-Knock");

endpoint.sendEmail(params);

request-body: from=sahan@example.com & to=someone@example.com & subject=Hi & text=Knock-Knock

####5. Constant Form Parameters

Form parameters which remain the same for every invocation can be declared as constants using @FormParams and @Param.

@POST("/emails/send")
@FormParams({@Param(name = "from", value = "sahan@example.com"),
             @Param(name = "to", value = "support@example.com")})
void contactSupport(@FormParams Map<String, String> params);

...

Map<String, String> params = new LinkedHashMap<String, String>();
params.put("subject", "Hi");
params.put("text", "Knock-Knock");

endpoint.contactSupport(params);

request-body: from=sahan@example.com & to=support@example.com & subject=Hi & text=Knock-Knock

####6. Batch Form Parameters

Like the query string, a form-url-encoded string may contain key-value pairs with same key but different values. These batch form parameters are identified with @FormParams on a map of type Map<String, Collection<CharSequence>>.

@POST("/emails/send")
void sendEmail(@FormParams Map<String, String> params);

...

List<String> ccValues = new ArrayList<String>();
values.add("one@example.com");
values.add("two@example.com");
values.add("three@example.com");

Map<String, String> params = new LinkedHashMap<String, Object>();
params.put("cc", ccValues);

...

endpoint.sendEmail(params);

request-body: ... cc=one@example.com & cc=two@example.com & cc=three@example.com