[ADP-366] Idempotency

Guidance

• MUST be idempotent for GET, PUT, and DELETE methods in any case.
• SHOULD implement idempotency for POST and PATCH methods.
  • See HTTP Headers - Idempotency-Key for implementation details.

Implementation Details

Idempotency-Key Header

When implementing idempotency for POST or PATCH requests:

1. The client SHOULD include an Idempotency-Key header with a unique value for each request.
2. The server MUST store the Idempotency-Key in a database or cache to manage consistent API behavior.
3. If the server receives a request with an Idempotency-Key it has seen before:
   • If the original request succeeded, return the same response.
   • If the original request failed, the server MAY retry the operation.
   • If the original request is still in progress, the server SHOULD return a 409 Conflict status.

Example:

POST /orders HTTP/1.1
Idempotency-Key: 123e4567-e89b-12d3-a456-426614174000

Idempotency Window

• The server SHOULD define a time window for which it guarantees idempotency.
• After this window expires, the server MAY forget the Idempotency-Key and treat a request as new.

Reference

• https://developer.mozilla.org/en-US/docs/Glossary/Idempotent

• https://datatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/

  • Notices: this is in draft, could change later.

• https://eda-visuals.boyney.io/visuals/understanding-idempotency

  

• https://www.youtube.com/watch?v=t99NvIazD68

Changelog

• 2024.09.24 Remove unwanted /api path in the samples