Parameters

Parameters are used to pass and add 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.In addition, List, SortedSet, and Set can be used where the generic type is one of the previously mentioned types such as 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 performed 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.

In order to enable JAX-RS to read a 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 will 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 previous example, HTTP GET to /books/1 or to /books/abcd would result in invokeWithBookId being called. If a HTTP GET request is 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 for example, 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 although applications sometimes use Cookies for various reasons, such as adding some stateless resource viewing information without embedding it into the URL such as the maximum number of items to retrieve. The CookieParam annotation is used to easily retrieve 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();
    }
}