+

Search Tips   |   Advanced Search

Define parameters for request representations to resources in RESTful applications


Overview

Use parameters as part of the URL or in the headers. Path parameters, matrix parameters, query parameters, header parameters, and cookie parameters are useful for passing in additional information to a request.

Multiple parameter types exist. JAX-RS enables access using annotated injected parameters.

We can use any basic Java primitive type including java.lang.String as parameters, as well as Java types with a constructor that uses a single String or a valueOf(String) static method. Additionally, we can use List, SortedSet, and Set interfaces where the generic type is one of the previously mentioned types, such as a Set when a parameter can have multiple values. To parse requests, use String as the parameter type to enable basic inspection and customization of error path responses.


Resource method parameter annotations

javax.ws.rs.PathParam

Path parameters are part of the URL. For example, the URL can include...

    /collection/{item}

...where {item} is a path parameter identifying item in the collection. Because path parameters are part of the URL, they are essential in identifying the request.

If parts of the URL are parameters, we can use a @javax.ws.rs.PathParam annotated parameter; for example: 

@javax.ws.rs.Path("/bookstore/books/{bookId}")
public class BooksCollection  {
    @javax.ws.rs.GET
    public String getSpecificBookInfo(@javax.ws.rs.PathParam("bookId") String theBookId)      {
        /* theBookId would contain the next path segment after /bookstore/books/  */
    }
}
In this example, requests to...

    /bookstore/books/12345

...assigns the value of 12345 to the theBookId variable.

javax.ws.rs.MatrixParam Matrix parameters are part of the URL. For example, if the URL includes the path segment...

    /collection;itemID=itemIDValue

...the matrix parameter name is itemID and itemIDValue is the value.

We can read matrix parameters with a @javax.ws.rs.MatrixParam annotated parameter; for example: 

@javax.ws.rs.Path("/bookstore/books")
public class BooksCollection  {
    @javax.ws.rs.GET
    public String getBookCollectionInfo(@javax.ws.rs.MatrixParam("page") int page,                                          @javax.ws.rs.MatrixParam("filter") String filter)      {
        /* This statement uses the page and filter parameters. */
    }
}
In this example, requests to...

    /bookstore/books;page=25;filter=test

...invoke the getBookCollectionInfo parameter so that the value for the page variable is set to 25 and the value for filter variable is set to test.

javax.ws.rs.QueryParam Query parameters are appended to the URL after a "?" with name-value pairs. For instance, if the URL is...

    http://example.com/collection?itemID=itemIDValue

...the query parameter name is itemID and itemIDValue is the value. Query parameters are often used when filtering or paging through HTTP GET requests.

We can read query parameters with a @javax.ws.rs.QueryParam annotated parameter; for example: 

@javax.ws.rs.Path("/bookstore/books")
public class BooksCollection  {
    @javax.ws.rs.GET
    public String getBookCollectionInfo(@javax.ws.rs.QueryParam("page") int page,
                                        @javax.ws.rs.QueryParam("filter") String filter)      {
        /* This statement uses the page and filter parameters. */
    }
}
In this example, requests to...

    /bookstore/books;page=25;filter=test

...invoke the getBookCollectionInfo parameter so that the value for the page variable is set to 25 and the value for filter variable is set to test.

javax.ws.rs.HeaderParam

Header parameters are HTTP headers. While there are pre-defined HTTP headers, we can also use custom headers. Headers often contain control metadata information for the client, intermediary, or server.

If a HTTP request header must be read, use the @javax.ws.rs.HeaderParam annotation; for example: 

@javax.ws.rs.Path("/bookstore/books/")
public class BooksCollection  {
    @javax.ws.rs.GET
    public String getBookCollectionInfo(@javax.ws.rs.HeaderParam("Range") String rangeValue)      {
        /* The rangeValue variable contains the value of the HTTP request header "Range" */
    }
}

In this example, requests to...

    /bookstore/books/

...with a Range HTTP request header value of bytes=0-499 invokes the method with bytes=0-499 as the value for the rangeValue variable.

javax.ws.rs.CookieParam

Cookie parameters are special HTTP headers. While cookies are associated with storing session identification or stateful data that is not accepted as RESTful, cookies can contain stateless information.

If an HTTP cookie is sent, such as mycustomid=customvalue123, we retrieve the value of mycustomid using: 

@javax.ws.rs.Path("/bookstore/books/")
public class BooksCollection  {
    @javax.ws.rs.GET
    public String getBookCollectionInfo(@javax.ws.rs.CookieParam("mycustomid") String mycustomid)      {
        /* The cookie value is passed to the mycustomid variable. */
    }
}
javax.ws.rs.FormParam

Form parameters are used when submitting a HTML form from a browser with a media type of application/x-www-form-urlencoded. The form parameters and values are encoded in the request message body in the form like the following:

    firstParameter=firstValue&secondParameter=secondValue

The javax.ws.rs.FormParam annotation enables access to individual form parameter values.

If a form is submitted and the entity value is firstName=Bob&lastName=Smith, we can retrieve the values of the form parameters using: 

@javax.ws.rs.Path("/customer")
public class Custommer  {
    @javax.ws.rs.POST
    public String postCustomerInfo(@javax.ws.rs.FormParam("firstName") String firstName,
                                   @javax.ws.rs.FormParam("lastName") String lastName)      {
        /* firstName would be "Bob" and secondName would be "Smith" */
    }
}

Avoid trouble: We can either use a single unannotated parameter to represent the message body or use multiple FormParam annotated parameters, but not both. Because the FormParam requires the request message body to be read and the message body is represented as a byte stream, the message body cannot be read again. The following code is not valid: 

@javax.ws.rs.Path("/bookstore/books")
public class BooksCollection  {
    @javax.ws.rs.POST
    public String postSpecificBookInfo(@javax.ws.rs.FormParam("bookId") String theBookId, String theRequestEntity)      {
        /* This code is invalid.  Can only use FormParam or a request entity parameter             like "String theRequestEntity" and not both */
    }
}
gotcha

Choose one of the following ways to define variables to read parameters.


Results

Your resource methods are defined so that they can be invoked with appropriate parameter values.


Related tasks

Define the resources
  • Define the URI patterns for resources
  • Define resource methods
  • Define the HTTP headers and response codes
  • Define media types for resources