Skip to content

API Design

First PublishedLast UpdatedByAtif Alam

APIs are contracts between teams and systems. A design review should state who calls whom, failure modes, and evolution rules so clients do not encode fragile assumptions.

For HTTP contracts, payload examples, and an API best-practices guide (plus Python FastAPI and Go chi layouts), use the dedicated API design library section.

REST, gRPC, and GraphQL

Section titled “REST, gRPC, and GraphQL”

REST over HTTP is the default for broad interoperability, caching on read-only resources, and tooling. gRPC fits low-latency internal calls, strongly typed contracts, and streaming. GraphQL helps aggregated reads for diverse clients but shifts complexity to resolvers, N+1 risks, and operation guardrails. Pick based on caller types and performance profile, not fashion.

HTTP Method Semantics

Section titled “HTTP Method Semantics”

Conventional mapping:

  • POST — create a resource or submit a non-idempotent action.
  • PUT — replace a resource (client sends full representation).
  • PATCH — partial update.

Document idempotency expectations per method; clients and intermediaries rely on these semantics.

Status Codes

Section titled “Status Codes”

4xx — client fixable (validation, auth, conflict, rate limit). 5xx — server-side failure (the client may retry with backoff if the operation is idempotent). Mixed semantics confuse alerting and dashboards.

See HTTP for operators for transport-level behavior.

Pagination

Section titled “Pagination”

Paginate every potentially large collection. Offset pagination is simpler but degrades at deep pages.Cursor-based pagination (opaque cursor tied to sort key) scales better under concurrent inserts.

Versioning

Section titled “Versioning”

Version APIs from launch (/v1/..., header negotiation, or similar). Breaking changes belong in new versions, not silent field renames clients cannot detect.

Idempotency Keys

Section titled “Idempotency Keys”

For retryable POST or monetary operations, accept an idempotency key so duplicate submissions collapse to one effect. Pair with server-side storage of outcomes for a bounded TTL.

Rate Limiting

Section titled “Rate Limiting”

Rate limit every public endpoint to protect the system and fair-share tenants. Return 429 with Retry-After when appropriate; document client expectations.

Related: Networking, Fault tolerance, design review checklist.