HTTP Headers

HTTP headers mainly store metadata and control information. There are some common headers shared in requests and responses but there are a few specific to either a request or a response. Developers should read the HTTP spec for a complete understanding of HTTP headers. Some of the more common HTTP headers are mentioned below in cases where JAX-RS provides convenient methods for the header.

Generally, to get the request header name and values, developers can use either an injected @HeaderParam annotated parameter/field/property or an injected @Context HttpHeaders parameter/field/property.

@Path("/example")
public ExampleResource {
    @Context HttpHeaders requestHeaders;

    @GET
    public void getSomething(@HeaderParam("User-Agent") String theUserAgent) {
        /* use theUserAgent variable or requestHeader's methods to get more info */
    }
}

To set response headers, developers can set them on a javax.ws.rs.core.Response return object.

@Path("/example")
public ExampleResource {
    @GET
    public Response getSomething() {
        return Response.ok(/* some entity */).header("CustomHeader", "CustomValue").build();
    }
}

Also, response headers can be set when a MessageBodyWriter#writeTo() method is called.

Common Headers

Content-Type

The Content-Type signals the media type of the request/response entity. The Content-Type header on requests can be read via HttpHeaders#getMediaType(). The Content-Type is set for responses when doing a javax.ws.rs.core.Response.ResponseBuilder#type() or javax.ws.rs.core.Response.ResponseBuilder#variant().

Content-Language

The Content-Language denotes what language the entity is in. To get the request entity language, use HttpHeaders#getLanguage(). To set the response entity language, use javax.ws.rs.core.Response.ResponseBuilder#language().

Content-Length

The Content-Length is useful for determining the entity's length. If possible, MessageBodyWriter entity providers will automatically set the Content-Length if possible, and some containers will set the response Content-Length if the entity is small. See the HTTP spec for more details on when this header is set and valid.

Common Request HTTP Headers

Accept

The Accept header is used to determine the possible response representations that the client prefers (i.e. XML over JSON but not plain text). When a resource method is effectively annotated with a @Produces, any incoming request must have a compatible Accept header value for the resource method to be selected. Clients can set quality parameters (priority ordering) for the best possible response and services generally try to honor the request. To get the best representation of a response, use either the HttpHeaders#getAcceptableMediaTypes() or Request#selectVariant() methods.

Accept-Language

Like the Accept header, Accept-Language lists the preferred languages. HttpHeaders#getAcceptableLanguages() will list the acceptable languages in a preferred order.

If-Match and If-None-Match

If a previous response had an ETag header, the client can re-use the ETag value with the If-Match or If-None-Match request header to do conditional requests (if the server application supported the If-Match/If-None-Match headers). For instance, a POST with an If-Match header and an old ETag value should only execute the POST request if the old ETag value is still valid. javax.ws.rs.core.Request#evaluatePreconditions() may help evaluate the If-Match and If-None-Match headers.

If-Modified-Since and If-Unmodified-Since

Like ETags, If-Modified-Since and If-Unmodified-Since are based on the Last-Modified date. Using either request header with a date, will set up a conditional request (if the server application supports the headers). For instance, a GET with an If-Modified-Since header of an old known date would allow the server to send back a response with just a HTTP status code of 304 (Not Modified). By sending back a HTTP status code of 304, the server is telling the client that the resource has not changed so there is no need to re-download the resource representation. This could save precious bandwidth for the client. javax.ws.rs.core.Request#evaluatePreconditions() may help evaluate the If-Modified-Since and If-Unmodified-Since headers.

Note that date formats are specified in the HTTP spec.

Common Response HTTP Headers

ETag

ETags or entity tags can be set. Like a hashcode, it is given to the client so a client can use various control request headers such as If-Match and If-None-Match for conditional requests. javax.ws.rs.core.Response.ResponseBuilder#tag() and javax.ws.rs.core.EntityTag are useful for ETags.

Expires

The Expires response header indicates for how long the response entity should be cached. It is useful to set for data that is not going to change for a known time length. Browsers use this response header to manage their caches among other user agents. javax.ws.rs.core.Response.ResponseBuilder#expires() can be used to set the Expires header.

Last-Modified

Last-Modified specifies the date when the resource was changed. A client can use the response value in combination with If-Modified-Since and If-Unmodified-Since request headers to perform conditional requests. javax.ws.rs.core.Response.ResponseBuilder#lastModified() can be used to set the Last-Modified header.