Code Quality
API Design

API Design

Non-Negotiables

  1. APIs are products. Design for consumers, not for today’s implementation.
  2. OpenAPI-first. If it’s not in the spec, it doesn’t exist.
  3. Backwards compatibility is the default. Breaking changes require a version strategy.
  4. Consistency beats creativity. Predictable APIs are cheaper to operate.

Minimum Requirements (Industry Standard Baseline)

Contract

  • Provide an OpenAPI specification.
  • Define:
    • authentication/authorization
    • request/response schemas
    • error model (see Error Handling)
    • pagination, filtering, sorting
  • Use stable field names; never repurpose a field.

HTTP Semantics

  • Use correct HTTP methods (GET/POST/PUT/PATCH/DELETE).
  • Use correct status codes.
  • Idempotency:
    • GET/PUT/DELETE must be idempotent
    • POST that creates resources should support idempotency keys when needed

Versioning & Compatibility

  • Additive changes are preferred (new optional fields, new endpoints).
  • Breaking changes require:
    • deprecation policy
    • migration window
    • explicit versioning (path/header) when unavoidable

Performance & Reliability

  • Pagination is mandatory for list responses.
  • Timeouts and retries must be defined and documented.
  • Provide correlation IDs end-to-end.

References

Database GovernanceError Handling Design