Parameters

Parameters can be used to pass in additional information to a request. Search queries, offsets/pages in a collection, and other information can be used. While parameters are sometimes used to add more verbs to HTTP, it is advised not to use parameters as a way to create new HTTP methods or to make existing HTTP methods break the generally understood attributes (i.e. idempotent).

Parameters can be any basic Java primitive type including java.lang.String as well as types with a constructor that takes in a single String or a valueOf(String) static method. Also, List, SortedSet, and Set can be used where the generic type is one of the previously mentioned types (i.e. a Set<String>) when a parameter can have multiple values.

When full control is needed for parsing requests, it is generally recommend that developers use a String as the parameter type so that some basic inspection can be done and developers can customize error path responses.

Query Parameters (@QueryParam)

Query parameters are one of the better known parameters. A query string is appended to the request URL with a leading "?" and then name/value pairs.

A few examples:

http://www.google.com/search?q=apache+wink

http://www.example.com/users?offset=100&numPerPage=20

In JAX-RS to read query parameters, add a parameter to the resource method and annotate with @QueryParam:

@Path("/example")
public class RootResource {
    @GET
    public Response invokeWithParameters(@QueryParam("q") String searchTerm) {
        if(q == null) {
            return Response.BAD_REQUEST;
        }
        /* do a search */
        return Response.ok(/* some entity here */).build();
    }
}

If a HTTP GET request to "/example?q=abcd" is made, searchTerm would have "abcd" as the value when invoked.

Matrix Parameters (@MatrixParam)

Matrix parameters are not as widely used on the Internet today. However, you can read a MatrixParam just as easily as any other parameter.

@Path("/")
public class RootResource {
    @GET
    public Response invokeWithParameters(@MatrixParam("name") String searchTerm) {
        if(q == null) {
            return Response.BAD_REQUEST;
        }
        /* do a search */
        return Response.ok(/* some entity here */).build();
    }
}