Skip to content

Latest commit

 

History

History
122 lines (108 loc) · 6.27 KB

10-Headers.md

File metadata and controls

122 lines (108 loc) · 6.27 KB
Raw

RESTful Best Practices

Headers make up a fundamental part of the RESTful communication with services.  As such headers are required in all responses.  For headers defined in the IANA standard list, APIs MUST be compliant with the respective public RFCs when using those headers.

10.1 Required Headers

Some headers supply critical information to the understanding of a representation.  These headers have requirements as defined below.

10.1.1 Request Headers

  • Accept: When not present the payload SHOULD be interpreted as application/json.
  • If-Match / If-None-Match: MUST be handled on PUT and POST requests when returning an ETag response header**.** MUST be used for validation if provided.
  • Prefer: MUST be used for to signal the request for asynchronous processing of an otherwise synchronous endpoint operation as specified by RFC 7240 and vice versa.

10.1.2 Response Headers

  • Cache-Control: SHOULD be provided in all responses.  To prevent caching the value SHOULD be "no-cache, no-store, must-revalidate". 

  • Content-Type: MUST be provided.

  • CORS headers SHOULD be provided in response to preflight OPTIONS requests for which CORS is enabled. The return should include:

    • Access-Control-Allow-Origin for all methods.  If CORS has been enabled, the value **SHOULD **be the value sent in the request's Origin header field.  It MUST NOT be a combined wildcard and domain.  When returning the Origin value in this field, the Vary header MUST contain the value Origin in the header list.

    • Access-Control-Allow-Methods on OPTIONS method response, and SHOULD be a list of the allowed methods that the service supports, e.g. "DELETE,GET,HEAD,OPTIONS,PATCH,POST,PUT".

    • **Access-Control-Allow-Headers on OPTIONS method response, and MUST include "Content-Type" **and for responses on endpoints which require authentication MUST include "Authorization" as well.

  • ETag: MUST be used to convey resource changes.  The ETag header MAY be the version.  If the ETag is set, Last-Modified SHOULD contain the date and time at which ETag was set.

  • **Location: SHOULD **be provided when a 201, 202, or 3XX status code is returned.  The url provided in the Location header MUST be an absolute url.

  • Vary: Vary is a list of headers which MUST be provided when the response payload or response headers would be different if the same representation was requested at the same url from a different user.  In Vary specify the list of headers which contribute to the change.

  • WWW-Authenticate: MUST be provided when a 401 status code is returned.  The value MUST be: Bearer realm="Realm", authorization_uri="AuthUrl" where:

10.2 Non-Standard Headers

Headers not defined by the IANA standards SHOULD NOT be used. Services MAY return non-standard headers if the service deems it appropriate, but clients of these services **MUST NOT **be required to read non-standard headers and drive business logic based on them.

10.3 Service Handling Requirements

Services MUST handle and allow headers with all lowercase characters as well as the documented canonical form.  Services header handling SHOULD be case insensitive where possible.  Headers MUST be in their standardize documented casing, however HTTP header fields are case insensitive.