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.status(Status.BAD_REQUEST).build();
        }
        /* 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.

Path Parameters (@PathParam)

Path parameters take the incoming URL and match parts of the path as a parameter. By including {name} in a @Path annotation, the resource can later access the matching part of the URI to a path parameter with the corresponding "name". Path parameters make parts of the request URL as parameters which can be useful in embedding request parameter information to a simple URL.

@Path("/books/{bookid}")
public class BookResource {
    @GET
    public Response invokeWithBookId(@PathParam("bookid") String bookId) {
        /* get the info for bookId */
        return Response.ok(/* some entity here */).build();
    }

    @GET
    @Path("{language}")
    public Response invokeWithBookIdAndLanguage(@PathParam("bookid") String bookId, @PathParam("language") String language) {
        /* get the info for bookId */
        return Response.ok(/* some entity here */).build();
    }
}

In the above, HTTP GET to /books/1 or to /books/abcd would result in invokeWithBookId being called. If a HTTP GET was issued to /books/1/en or /books/1/fr or /books/abcd/jp, then invokeWithBookIdAndLanguage would be invoked with the appropriate parameters.

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 name) {
        if(name == null) {
            return Response.status(Status.BAD_REQUEST).build();
        }
        return Response.ok(/* some entity here */).build();
    }
}

Header Parameters (@HeaderParam)

Header parameters are useful especially when there are additional metadata control parameters that need to be passed in (i.e. security information, cache information, and so forth).

@Path("/")
public class RootResource {
    @GET
    public Response invokeWithParameters(@HeaderParam("controlInfo") String controlInfo) {
        if(controlInfo == null) {
            return Response.status(Status.BAD_REQUEST).build();
        }
        return Response.ok(/* some entity here */).build();
    }
}

CookieParameters (@CookieParam)

In a REST application, requests are stateless but sometimes applications use Cookies for various reasons (i.e. put some stateless resource viewing information without embedding it into the URL such as the maximum number of items to retrieve). CookieParam is used to easily get the information.

@Path("/")
public class RootResource {
    @GET
    public Response invokeWithParameters(@CookieParam("max") String maximumItems) {
        if(userId == null) {
            return Response.status(Status.BAD_REQUEST).build();
        }
        return Response.ok(/* some entity here */).build();
    }
}