HTTP implementation

APIs MUST follow standard HTTP semantics to ensure consistency, predictability and interoperability. This section outlines good practice, but refer to official specs when needed:

Hypermedia (HATEOAS)

A RESTful API MUST implement Hypermedia as the Engine of Application State (HATEOAS) to be classified as Richardson Level 3. HATEOAS allows clients to navigate and manipulate resources dynamically without requiring prior knowledge of specific URIs.

However, HATEOAS is NOT required for APIs in this organisation. But if implemented:

• The API MUST provide hypermedia links to guide clients on available actions.

• These links SHOULD use standard link relations where possible (e.g. as defined in RFC 8288) and MUST be documented in the API's OpenAPI definition.

HTTP verbs and resource operations

APIs MUST use standard HTTP methods correctly to ensure predictable behaviour.

• APIs MUST only expose necessary HTTP methods and MUST document them in the OpenAPI definition.

• APIs SHOULD return 405 Method Not Allowed for unsupported HTTP methods instead of silently ignoring them.

• APIs MUST adhere to the standard HTTP semantics defined in RFC 9110, including idempotency rules.

• Non-standard HTTP verbs MUST NOT be used.

Standard HTTP methods and usage

• GET, HEAD, OPTIONS, and DELETE MUST NOT modify resources.

• PUT and DELETE MUST be idempotent to ensure safe retries.

• PATCH is NOT idempotent unless explicitly designed to be.

• POST MUST be used for non-idempotent operations such as resource creation.

HTTP request headers

PIs MUST support and handle the following request headers:

APIs SHOULD support the following request headers:

APIs MAY support additional request headers:

HTTP response headers

APIs SHOULD return the following response headers:

The following optional response headers MAY apply:

Return HTTP status codes

The server MUST return the correct HTTP status code for each API operation, as per RFC 9110. The table below lists common status codes, but others MAY be used if needed.

• "✅ Yes" means the status code applies to that operation.

• An empty cell means the code is not usually used for that operation.

Caveats and edge cases

• While PATCH can return 200 OK with the updated resource, 202 ACCEPTED is preferred for asynchronous processing. But some implementations MAY choose to return 200 OK instead.

• 304 NOT MODIFIED applies only when the API supports caching with conditional GET requests. The server MAY return 304 NOT MODIFIED if the client's cached version is still valid.

• Use 409 CONFLICTwhen there's a conflict with the current state of the target resource. Use 422 UNPROCESSABLE ENTITY when the server understands the request but can't process it due to semantic errors.

• Use 409 CONFLICTwhen there's a conflict with the current state of the target resource. Use 422 UNPROCESSABLE ENTITY when the server understands the request but can't process it due to semantic errors.

• While 415 UNSUPPORTED MEDIA TYPE is typically used for POST, PUT and PATCH, it MAY apply to GET if a body is sent with an unsupported media type --- although this is rare.

• 412 PRECONDITION FAILED and 428 PRECONDITIONS REQUIRED are typically used for POST, PUT and PATCH. However, some designs MAY also apply them to DELETE if preconditions are enforced.

• Use 428 PRECONDITIONS REQUIRED when the server requires the request to be conditional, typically to prevent the "lost update" problem. Use 412 PRECONDITION FAILED when a precondition specified in the request isn't met.

• Typically our API platform will apply rate limiting and return 429 TOO MANY REQUESTS when appropriate.

• Some designs MAY extend the use of 501 NOT IMPLEMENTED to other methods if a particular method is not supported by the server.