5. APIs, Contracts, and Idempotency

An API is a contract between independently changing components. HTTP defines important semantics such as safe and idempotent methods. Idempotency matters because clients may not know whether a timed-out operation succeeded, and a retry can otherwise repeat a side effect.

Evidence: S9, S10, S11

Example

POST /payments

Idempotency-Key: order-9381-payment-1


Retry with the same key -> same business effect, not a second charge

Idempotency-Key here is an example of an API-level contract. RFC 9110 defines idempotent HTTP methods; it does not make an arbitrary POST idempotent just because the client retries it.

Checklist

• Resource and operation semantics are clear.

• HTTP method semantics are used correctly.

• State-changing operations have an explicit duplicate/retry strategy.

• Idempotency keys or equivalent protection exist where duplicate side effects are unacceptable.

• Timeout behavior is defined for clients and downstream calls.

• Error responses are consistent and actionable.

• Large collections are paginated.

• Breaking changes require a versioning/evolution strategy.

• Backward compatibility is preferred where practical.

• Rate limits and quotas are defined for constrained resources.

• Authentication and authorization rules are defined per operation.

• API telemetry includes correlation/trace context.

Evidence: S9, S10, S11, S35, S45