Define the HTTP headers and response codes for RESTful applications

HTTP headers and status codes are useful to help intermediary and client programs understand information about requests and responses for applications. HTTP headers contain metadata information. HTTP status codes provide status information about the response.

See the HTTP 1.1 specification to become familiar with HTTP headers and HTTP status codes.

HTTP headers contain metadata information such as security authentication information, the user agent used, and cache control metadata. Standard HTTP headers are defined in the HTTP specification; however, we can use custom HTTP headers, if necessary.

We can read HTTP headers from the request and set the headers in the response. There are a set of common request and response headers, but there are also unique request and unique response headers. JAX-RS provides the HttpHeaders injectable interface and the @HeaderParam parameter annotation for reading HTTP headers. If a javax.ws.rs.core.Response object is returned from a resource method, we can set HTTP headers on the response. Also, we can set HTTP headers when an entity is written using the MessageBodyWriter interface.

We can set HTTP response status codes to help client programs understand the response. While responses can contain an error code in XML or other format, client programs can quickly and more easily understand an HTTP response status code. The HTTP specification defines several status codes typically understood by clients.

Tasks

• To read a specific request header, add a @javax.ws.rs.HeaderParam annotated parameter.

  @javax.ws.rs.Path("/bookstore/books/{bookID}")
  public class Book {
     @javax.ws.rs.GET
     public String retrieveSpecificBookInformation(@javax.ws.rs.HeaderParam("User-Agent") String theUserAgent) {
         /* The book ID was sent in a HTTP request header with the name "bookID". */
     }
  }
  

• To read any request header, use the @javax.ws.rs.core.Context javax.ws.rs.core.HttpHeaders injected object.

  @javax.ws.rs.Path("/bookstore/books/{bookID}")
  public class Book {
     @javax.ws.rs.GET
     public String retrieveSpecificBookInformation(@javax.ws.rs.core.Context HttpHeaders requestHeaders) {
         /* Call methods on "requestHeaders" to get any request header sent by the client. */
         List<String> bookIdValues = requestHeaders.getRequestHeader("User-Agent");
     }
  }
  

• To set a response status code or header, return a javax.ws.rs.core.Response object and build the response with the appropriate status code and headers.

  @javax.ws.rs.Path("/bookstore/books/{bookID}") public class Book {
     @javax.ws.rs.GET public javax.ws.rs.core.Response retrieveSpecificBookInformation() {
         return Response.status(200).header("responseHeaderName", "responseHeaderValue").header("anotherResponseHeaderName", "foo").build();
     }
  }
  

We have used HTTP headers to read request headers and set response status codes and headers for JAX-RS web applications.

Define the resources in RESTful applications

Define the URI patterns for resources in RESTful applications

Define resource methods for RESTful applications

Define parameters for request representations to resources in RESTful applications

Define media types for resources in RESTful applications