Headers

This section details the header usage, particularly where there are guidelines additional to the HTTP specification. Most of the headers detailed below are not required to be supported in most scenarios, but when any of the below headers are used, they MUST follow the constraints within the HTTP specification and within this section of the handbook.

Representation headers

Representation headers
Header	Type	Description
Content-Encoding	Request, Response	If a response body is encoded, this header MUST reflect the encoding used. Otherwise, this header MUST be omitted from the response. Requests including this header with an encoding not supported by the server MUST be rejected with a `415 Unsupported Media Type` status code and appropriate error response model. See below for more details.
Content-Language	Request, Response	If a response body is intended for an audience who speak a particular language (or languages), this header SHOULD be used to indicate that language (or those languages). If this header is included in a request it MAY be used by the server to classify the language of the incoming content appropriately.
Content-Location	Request, Response	When applicable, the `Content-Location` response header SHOULD be used to indicate the permanent location of the returned resource. See below for more details. For requests, the `Content-Location` MUST be ignored by the server except for the purpose of logging or otherwise recording request metadata.
Content-Type	Request, Response	For all responses with bodies, this header MUST be included and indicate the content type of the body. Requests including this header with a content type not supported by the server MUST be rejected with a `415 Unsupported Media Type` status code and appropriate error response model.

Content encoding

By default, responses SHOULD be encoded with gzip. If a request specifies a preference for an unsupported encoding in the Accept-Encoding header, responses MUST NOT be encoded. If the Accept-Encoding header requires that an unsupported encoding be used, requests MUST be rejected with a 406 Not Acceptable status code and and appropriate error response model in an unencoded body.

Encoded requests MAY be supported in cases where clients need to send large request bodies. If request encoding is supported at all, gzip SHOULD be permitted.

Content location

The Content-Location response header can provide valuable information to the client, particularly for state-changing methods. The advantage to providing a Content-Location header is that a client can always depend on this header to provide the permanent location of the content returned in a response body.

For responses to POST requests which return a 201 status along with the created resource, Content-Location SHOULD be included and match Location.
For responses to PUT or PATCH requests which modify the resource at the request URI and return a 200 status along with the modified resource, Content-Location SHOULD be included and match the request URI.
For responses to POST, PUT, PATCH, or DELETE requests which return a 202 status and include a resource representing the status of the request, Content-Location SHOULD be included and contain a URI where this request status may be obtained.
For responses to any other POST, PUT, PATCH, or DELETE requests which include a resource in the response body which may be found at a permanent URI, Content-Location SHOULD be included and contain this URI.

The body of a response which includes a Content-Location header MUST be identical to the body of the response to a successful GET request made to the URI provided in that Content-Location header.

Negotiation headers

Negotiation headers
Header	Type	Description
Accept	Request	For requests including this header, the server SHOULD attempt to return resources in a format specified as acceptable. Requests including this header with only formats not supported by the server MUST be rejected with a `406` status code and appropriate error response model. This header MUST NOT be required.
Accept-Charset	Request	For requests including this header, the server SHOULD attempt to return resources in a character set specified as acceptable. If this header is not included, the response MUST use `utf-8`. Requests including this header with only character sets not supported by the server MUST be rejected with a `406` status code and appropriate error response model. This header MUST NOT be required.
Accept-Encoding	Request	For requests including this header, the server SHOULD attempt to return resources encoded in an acceptable way. If this header is not included, the response SHOULD use `gzip`. See above for more details. This header MUST NOT be required.
Accept-Language	Request	For requests including this header, the server MAY attempt to return resource in an acceptable language. This header MUST NOT be required. Furthermore, the value of this header MUST NOT prevent a request from succeeding.
Accept-Ranges	Response	If a resource supports range requests, this header SHOULD be used to indicate what ranges are supported.
Allow	Response	This header MUST be used to indicate allowable request methods in a `405` response. If deemed useful, it MAY be included in any other response.
Upgrade	Request, Response	This header MAY be supported for requests and included in responses, in keeping with HTTP standards, to negotiate the use of a new protocol on the same connection. This header MUST NOT be supported except for operations which exist specifically to switch protocols^[1]. The successful outcome of an operation that supports this header (either for requests or responses) MUST be a `101 Switching Protocols` status.

Authentication headers

Authentication headers
Header	Type	Description
Authorization	Request	The server MUST support this header for any form of authentication.
WWW-Authenticate	Response	This header MUST be supplied for responses to requests which need to be authenticated to be successful or requests where credentials are supplied but invalid. It MUST be supplied for all responses with a `401` status.

Validator headers

Validator headers
Header	Type	Description
ETag	Response	The `ETag` header MAY be supplied with the response to any `GET` or `HEAD` request, or with the response to any request that uses a resource's canonical schema. If supported, the `ETag` SHOULD be a quoted lowercase base-36 string, at least 16 characters in length (e.g., `"md9weho39cn2302n"`) and MUST be based on a checksum or hash of the resource that guarantees it will change if the resource changes. The value MUST have a `W/` prefix if strong ETag semantics are not supported. Even if `W/`-prefixed, an `ETag` MUST be guaranteed to change if any properties are changed that are directly mutable by a client.
Last-Modified	Response	The `Last-Modified` header MAY be supplied with the response to any `GET` or `HEAD` request. The `Last-Modified` MUST be supplied for any resources that support the `If-Modified-Since` or `If-Unmodified-Since` headers for any methods. The `Last-Modified` header MUST contain a valid HTTP-date value in GMT (e.g., `Tue, 15 Nov 1994 12:45:26 GMT`) and MUST NOT be a date/time that occurs in the future.

`ETag` support

The ETag header MUST be returned for GET and HEAD operations on a resource that supports If-Match or If-None-Match headers for any operation. If the ETag header is returned for any resource within a service, it SHOULD be returned for all resources in the service. If the ETag header is returned for GET operations on a resource, it SHOULD be returned on all operations that return the resource's canonical schema. The ETag header MUST NOT be returned for collection operations, but a resource MAY also include an etag property (with the same format and value) in its canonical schema, facilitating retrieval of ETag values when using collection operations. The etag property MUST NOT be included in non-canonical schemas.

`Last-Modified` support

The Last-Modified header MUST be returned for GET and HEAD operations on a resource that supports If-Unmodified-Since or If-Modified-Since headers for any operation. If the Last-Modified header is returned for any resource within a service, it SHOULD be returned for all resources in the service.

Conditional headers

Conditional headers provide a means for consumers to efficiently ensure a cached resource is up-to-date and use optimistic locking in order to mitigate race conditions.

Conditional headers
Header	Type	Description
If-Match	Request	This header MAY be supported for any request; it is particularly applicable to `POST`, `PUT`, `PATCH`, and `DELETE` requests. If this condition fails, the server MUST send a `412` status and an appropriate error response model.
If-None-Match	Request	This header MAY be supported for any request; it is particularly applicable to `GET` and `HEAD` requests. If this condition fails for a `GET` or `HEAD` request, the server MUST send a response with a `304` status and no body. If it fails for a request of any other method, the server MUST send a `412` status and an appropriate error response model.
If-Unmodified-Since	Request	This header SHOULD NOT be supported for any request. It addresses similar needs to the `If-Match` header, but because of its increased precision, documentation SHOULD encourage clients to use `If-Match`. If supported, and this condition fails, the server MUST send a `412` status and an appropriate error response model. If a client supplies any value other than an HTTP-date in this header, the server MUST send a `400` status and an appropriate error response model.
If-Modified-Since	Request	This header SHOULD NOT be supported for any request. It addresses similar needs to the `If-None-Match` header, but because of its increased precision, documentation SHOULD encourage clients to use `If-None-Match`. If supported, and this condition fails for a `GET` or `HEAD` request, the server MUST send a response with a `304` status and no body. If it fails for a request of any other method, the server MUST send a `412` status and an appropriate error response model. If a client supplies any value other than an HTTP-date in this header, the server MUST send a `400` status and an appropriate error response model.
If-Range	Request	This header MAY be supported for requests which support the `Range` header. If this condition fails, the server MUST ignore the `Range` header and send the entire resource.

Recommended `If-Match` support

The If-Match header SHOULD be supported for all POST^[2], PUT, PATCH, and DELETE operations on a resource for which an ETag header is returned.

Required checks for unsupported conditional headers

An unsupported conditional header in a POST, PUT, PATCH, or DELETE request SHOULD cause the request to fail with a 400 status code and an appropriate error response model.

If an ETag header is returned for a resource, an unsupported If-Match or If-None-Match header in a POST, PUT, PATCH, or DELETE request that operates directly on that resource MUST cause the request to fail with 400 Bad Request status.

If a Last-Modified header is returned for a resource, an unsupported If-Unmodified-Since or If-Modified-Since header in a POST, PUT, PATCH, or DELETE request that operates directly on that resource MUST cause the request to fail with 400 Bad Request status.

An unsupported conditional header in a GET or HEAD request MAY be ignored.

CORS headers

Support for Cross-Origin Resource Sharing (CORS) MAY be implemented by any service. The following guidelines apply to services which opt to implement support for CORS.

CORS headers
Header	Type	Description
Access-Control-Allow-Origin	Response	This header MUST be returned when a request is made from a white-listed origin. In this case, its value SHOULD match the value of the request's `Origin` header.
Access-Control-Allow-Credentials	Response	This header SHOULD be included with a value of `true` if cookies and credentials may be used. Otherwise it SHOULD be omitted.
Access-Control-Expose-Headers	Response	This header SHOULD be used to list which response headers should be made accessible to the client apart from `Cache-Control`, `Content-Language`, `Content-Type`, `Expires`, `Last-Modified`, and `Pragma`, which are all exposed by default.
Access-Control-Max-Age	Response	This header SHOULD be included with responses to preflight requests to indicate how long a client may cache the results.
Access-Control-Allow-Methods	Response	This header SHOULD be included with responses to preflight requests to indicate what request methods are permissible.
Access-Control-Allow-Headers	Response	This header MAY be included with any responses to preflight requests to indicate what request headers are permissible. It MUST be included in responses to requests including the `Access-Control-Request-Headers` header.
Access-Control-Request-Method	Request	This header SHOULD be understood and utilized in order to formulated responses to preflight requests.
Access-Control-Request-Headers	Request	This header SHOULD be understood and utilized in order to formulate responses to preflight requests.
Origin	Request	This header MUST be understood and utilized by services implementing support for CORS.

Preference headers

Preference headers
Header	Type	Description
Prefer	Request	This header SHOULD be supported for `POST`, `PUT`, and `PATCH` requests where it may be expensive (in terms of bandwidth or computation) to return the created or modified resource. If the client supplies `return=minimal`, a successful response MUST have a `201 Created` or `204 No Content` status and include no body. If `return=representation` is supplied, a successful response MUST include the acted-upon resource. Whether the resource is included in the response by default is up to the implementors of the service.
Preference-Applied	Response	This header MAY be returned with responses to requests which include a `Prefer` header but is usually not necessary as it is only needed when the client does not have any other clear indicators as to whether its preference was applied.

Context headers

Context headers
Header	Type	Description
From	Request	This header allows a client to provide an email address where the maintainer of the client system may be contacted. Its value MUST NOT affect the outcome of any request.
Referer	Request	This header allow a client to reference where the request URI was obtained. Its value MUST NOT affect the outcome of any request.
Server	Response	This header SHOULD be provided in all responses and SHOULD contain the public-facing name and version number (including any minor and patch version) of the service responsible for handling the request.
User-Agent	Request	This header allows a client to report information about itself. It SHOULD be logged with a request, but MAY be otherwise ignored.

Control headers

Control headers
Header	Type	Description
Age	Response	This header is used by caching servers to indicate the age of a request.
Cache-Control	Request, Response	This header specifies directives for caches. It MAY be supported if the presence of caches is anticipated.
Date	Request, Response	This header represents the time a request or response was originally sent, and MUST be included in responses. When included by requests, the server MUST NOT presume that the client's clock is accurate.
Expect	Request	This header is used in conjunction with the `100` status code and MAY be supported.
Expires	Response	This header indicates when a response will become stale and should be purged from caches. It MAY be supported if the presence of caches is anticipated.
Host	Request	This header indicates the host and port for the target URI of the request. If it is omitted or duplicated, the request MUST be rejected with a `400` status and appropriate error response model.
Location	Response	This header is required for certain status codes. The semantics for its usage is dictated by the status code it is paired with.
Max-Forwards	Request	This header is used by proxies in conjunction with `TRACE` and `OPTIONS` requests and MAY be ignored by the server.
Pragma	Request	This header specifies directives for caches. It MAY be ignored.
Range	Request	This header MAY be supported for large resources where clients might want to obtain only a resource in separate parts. It MUST be ignored for any requests with a method other than `GET`.
Retry-After	Response	This header MAY be sent with either a `503` status to indicate when a service is expected to be available again or with any `3xx` status to indicate how long a client should wait before executing a redirect. It MUST contain either a valid HTTP-date value or an integer representing a number of seconds.
TE	Request	This header is used to specify what transfer codings (besides chunked) a client is willing to accept and MAY be ignored.
Vary	Response	This header specifies what request fields may affect the outcome of a request. It MAY be supported if the presence of caches is anticipated or to proactively signal support for different content format, encodings, languages, etc.
Warning	Response	This header gives additional information that might not be conveyed in the status code and doesn't represent a total failure. It MAY be supported, particularly if the presence of caches is anticipated.

Tracing headers

Tracing headers allow services to log and propagate the context of individual requests and requests that are part of a larger context.

A value for one of these headers MAY include ASCII alphanumerics and any of following segment separators: space ( ), comma (,), hyphen, (-), and underscore (_) and MAY have a length up to 1024 bytes. A value MUST be considered invalid and MUST be ignored if that value includes any other character or is longer than 1024 bytes.

A value for one of these headers SHOULD be considered invalid and SHOULD be ignored if that value is known to be of static origin (such as an all-zero UUID) or insufficiently unique (such as a value with fewer than 8 characters).

A value for the X-Correlation-ID header MUST be considered invalid and MUST be ignored if it is supplied by a client known to be untrusted (that is, a client not written and operated by IBM itself). This directive does not apply to a value for X-Request-ID.

If a value for one of these headers is invalid or not supplied in a request, the service MUST generate a random (version 4) UUID to use in place of a client-supplied value.

Tracing headers
Header	Type	Description
X-Request-ID	Request, Response	The supplied or generated value of this header MUST be logged for a request and repeated in a response header for the corresponding response. The same value MUST NOT be used for downstream requests or between retries of those requests. Documentation for a service SHOULD encourage all client developers to supply this header with a random UUID.
X-Correlation-ID	Request, Response	The supplied or generated value of this header MUST be logged for a request and repeated in a response header for the corresponding response. The same value MUST be used for downstream requests and retries of those requests. Documentation for a service SHOULD encourage internal client developers to supply this header with a random UUID or (if available) a valid, trusted upstream value.

Rate limiting headers

The standard Retry-After header MUST be returned in a response with status code 429 for any implementation of rate limiting^[3].

Retry-After header
Header	Type	Description
Retry-After	Response	If rate limiting is active, this header MUST indicate how long the user agent should wait before making a follow-up request. The value of this field can be either an HTTP-date or a number of seconds to delay after the response is received.

The following headers, while not a part of the HTTP specification, are common practice^[4] and MAY be used for any implementation of rate limiting.

Rate limiting headers
Header	Type	Description
X-RateLimit-Limit	Response	If rate limiting is active, this header MUST indicate the number of requests permitted per hour.
X-RateLimit-Remaining	Response	If rate limiting is active, this header MUST indicate the number of requests remaining in the current rate limit window.
X-RateLimit-Reset	Response	If rate limiting is active, this header MUST indicate the time at which the current rate limit window resets, as a UNIX timestamp.

Version headers

Header	Type	Description
IBM-API-Version	Request	This header MUST be supplied to services that support it. The value of this header MUST be the version of the API requested by the client.

Custom headers

There are times where service-specific functionality may need to be implemented with custom headers. In these cases, support for custom request or response headers MAY be implemented. However, custom headers SHOULD NOT be required for basic usage of a given API.

When naming custom headers, care should be taken to disambiguate them as much as possible. They SHOULD NOT be prefixed with X-. If a custom header is by nature limited in scope to IBM-specific products and services it SHOULD begin with IBM- or IBM-PRODUCT- where PRODUCT is, for example, Watson. Custom header names SHOULD be constructed from title-cased, hyphen-separated words. However, as with all headers, they MUST be handled in a case-insensitive way.

Request headers as query parameters

In cases where a request header may be inconvenient for a client to supply request header functionality MAY be duplicated as query parameters. In these cases, the name of the query parameter should be as close to the name as the header as possible while still complying with all the rules for query parameter names. For example, the request header If-Match would be exposed as the query parameter if_match.

That is, services MUST NOT expect or encourage clients to handle protocol switching as a part of operations which may result in normal, successful (2xx) HTTP responses. ↩︎
If-Match is only applicable to POST requests which mutate or operate on an existing resource, such as those used for exceptional operations. ↩︎
The Retry-After header is defined in IETF RFC 7231. The rate-limiting implementation in CloudFlare does provide the Retry-After header in 429 responses. ↩︎
These headers are used by Twitter, GitHub){: external}, Atlassian, and others. ↩︎