api-design

Define the contract first with typed input and output schemas, then evolve it additively: only add optional fields, new enum values, and new endpoints. Never remove fields, change types, or make optional fields required, since consumers depend on every observable behavior.

Public APIs should use RFC 9457 Problem Details with the application/problem+json content type, including type, title, status, and detail members. Internal APIs with a single frontend can use a simpler consistent shape with a machine-readable error code and correct HTTP status.

Require a client-provided Idempotency-Key header, claim it atomically scoped to the authenticated user, and store the response for replay. Return 409 if the same key arrives with different parameters, and keep a durable operation identity so retries never duplicate charges or records.

Return 400 when the request representation itself cannot be parsed, such as malformed JSON. Return 422 when parsing succeeds but the value fails the endpoint schema or business validation, and document whichever mapping you choose consistently.

Prefer evolving without versioning by making only additive changes and following Postel's Law. When breaking changes are unavoidable, use date-based version pinning like Stripe for paying customers, or URL path versioning as a pragmatic default for public APIs.

The top OWASP risks are broken object-level authorization, where any authenticated user can access any object, and mass assignment from unvalidated request bodies. Scope lookups to the authenticated principal, validate input with closed schemas, and never trust third-party API responses without validation.