API Design for Backend Services

Design Priority

An API is a contract. Good API design makes correct client behavior obvious and incorrect behavior harder to ship.

Resource Shape

• Use nouns for resources and verbs for commands only when a resource model is awkward.
• Keep identifiers stable and opaque.
• Return consistent envelope or bare-resource shapes; do not mix casually.
• Make pagination, filtering, sorting, and field selection explicit.

Error Shape

Every error should answer:

• What happened?
• Can the client retry?
• Which field or dependency caused it?
• How can the client correlate this with server logs?

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests.",
    "retry_after_seconds": 30,
    "request_id": "req_123"
  }
}

Idempotency

Use idempotency keys for create operations that may be retried by clients, queues, or workflow engines. This matters for payments, media generation, job creation, and external API orchestration.

Versioning

Prefer additive changes. When breaking changes are unavoidable, version the external contract and document the migration path.

AI API Twist

For LLM and media APIs, expose operational state:

• queued
• running
• succeeded
• failed
• canceled

Do not force clients to hold open a request while expensive work runs.