Defining parameters for request representations to resources in RESTful applications
Parameters are used to pass and add additional information to a request. You can 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.
About this task
Multiple parameter types exist. Java™ API for RESTful Web Services (JAX-RS) enables easy access to all the types of parameters using annotated injected parameters.
You 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, you 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. If you need to parse requests, then use
String as the parameter type to enable you to complete basic inspection
and customization of error path responses.
JAX-RS provides the following annotations to use on resource method parameters to specify that the resource method can be invoked with correct parameter values.
- javax.ws.rs.PathParam annotation
Path parameters are part of the URL. For example, the URL can include
/collection/{item}
, where{item}
is a path parameter that identifies the 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, you can use a @javax.ws.rs.PathParam annotated parameter; for example:
In this example, requests to@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/ */ } }
/bookstore/books/12345
assigns the value of12345
to thetheBookId
variable.- javax.ws.rs.MatrixParam annotation
Matrix parameters are part of the URL. For example, if the URL includes the path segment,
/collection;itemID=itemIDValue
, the matrix parameter name isitemID
anditemIDValue
is the value.You can read matrix parameters with a @javax.ws.rs.MatrixParam annotated parameter; for example:
In this example, requests to@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. */ } }
/bookstore/books;page=25;filter=test
invoke thegetBookCollectionInfo
parameter so that the value for thepage
variable is set to25
and the value forfilter
variable is set totest
.- javax.ws.rs.QueryParam annotation
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 isitemID
anditemIDValue
is the value. Query parameters are often used when filtering or paging through HTTP GET requests.You can read query parameters with a @javax.ws.rs.QueryParam annotated parameter; for example:
In this example, requests to@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. */ } }
/bookstore/books;page=25;filter=test
invoke thegetBookCollectionInfo
parameter so that the value for thepage
variable is set to25
and the value forfilter
variable is set totest
.- javax.ws.rs.HeaderParam annotation
Header parameters are HTTP headers. While there are pre-defined HTTP headers, you 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 aRange
HTTP request header value ofbytes=0-499
invokes the method withbytes=0-499
as the value for therangeValue
variable.- javax.ws.rs.CookieParam annotation
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 asmycustomid=customvalue123
, you can retrieve the value of themycustomid
variable using the following example:@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 annotation
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 easy access to individual form parameter values.If a form is submitted and the entity value isfirstName=Bob&lastName=Smith
, you can retrieve the values of the form parameters using the following example:@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: You 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 */ } }
Choose one of the following ways to define variables to read parameters.
Procedure
Results
Your resource methods are defined so that they can be invoked with appropriate parameter values.