+

Search Tips   |   Advanced Search

Define parameters for request representations to resources in RESTful applications

Parameters are used to pass and add additional information to a request. 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. Java API for RESTful Web Services (JAX-RS) enables easy access to all the types of parameters using annotated injected parameters.

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. If we need to parse requests, then use String as the parameter type to allow us 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, 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 annotation

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 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 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 annotation

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 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 as mycustomid=customvalue123, we can retrieve the value of the mycustomid 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 is firstName=Bob&lastName=Smith, we 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" */
   }
}

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 */
   }
}

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


Tasks

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


Example

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