api-and-interface-design

Define the contract first with typed schemas, prefer adding optional fields over modifying existing ones, and follow the One-Version Rule by extending rather than forking. Paginate list endpoints from the start and use consistent naming conventions across all endpoints.

Derive the key from the client or an immutable identifier, never from a per-attempt UUID or timestamp. Claim it atomically with a unique constraint insert, reject the same key with a different payload, and set retention longer than the longest retry path including dead-letter replay.

Validation belongs at system boundaries: route handlers, form submissions, external service responses, and environment configuration. Internal functions sharing type contracts should trust already-validated data rather than re-validating.

Use PATCH for partial updates where only provided fields change, which is what clients actually want. PUT requires sending the full object every time and is appropriate only for complete resource replacement.

Hyrum's Law states that all observable behaviors of an API will be depended on by somebody, regardless of the documented contract. This means every public behavior is a commitment, so avoid leaking implementation details and plan deprecation at design time.