Defining 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.

Before you begin

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

About this task

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

You 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, you can set HTTP headers on the response. Also, you can set HTTP headers when an entity is written using the MessageBodyWriter interface.

You 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 that are typically understood by clients.

• 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();
      }
  }

Results

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