Skip to content

API Design

First PublishedLast UpdatedByAtif Alam

Use this section when you need shared vocabulary across product, backend, and platform teams: how URLs and HTTP semantics line up, what JSON contracts look like in practice, and how to lay out a small service in Python (FastAPI) or Go (chi). It complements the architecture-focused API design page in System design, which covers REST vs gRPC vs GraphQL tradeoffs at review time.

Mini Glossary Of Terms

Section titled “Mini Glossary Of Terms”
  • OpenAPI — Machine-readable API description (often openapi.yaml); source of truth for docs, mocks, and contract tests.
  • DTO (data transfer object) — Request/response shapes at the HTTP boundary; separate from persistence or domain models.
  • Resource — A type of thing your API exposes (for example users, orders), usually identified in the path.
  • Idempotency — Repeating the same request does not change outcome beyond the first success (safe for retries).
  • Idempotency-Key — Client-supplied header so a POST (or similar) can be retried without double effects.
  • ETag / If-Match — Version token on a resource; clients send If-Match on updates for optimistic concurrency.
  • Cursor (pagination) — Opaque token pointing at a position in a sorted list; preferred for large or changing collections.
  • RBAC / ABAC — Role- or attribute-based access control; enforced in the domain layer, not only on routes.
  • mTLS — Mutual TLS for service-to-service identity at the transport layer.
  • OAuth2 / OIDC — Standard flows for user and delegated access tokens.
  • Trace ID / correlation ID — Identifier carried across logs and services for one logical request.
  • Handler (transport) — Thin HTTP layer: parse input, call services, map errors to HTTP.
  • Middleware — Cross-cutting code (logging, auth, rate limits) that wraps handlers.
  • 415 Unsupported Media Type — Often returned when Content-Type does not match the body the server can parse (for example missing application/json on a JSON body).
Section titled “Recommended Reading Order”
  1. REST HTTP Fundamentals — contract surface fundamentals: URL modeling, method semantics, status/error contracts, validation, and idempotency.
  2. API best practices — operational guardrails for security, observability, reliability, performance, and rollout checks.
  3. Payloads and responses — JSON envelopes, verbs, headers, pagination examples, health checks, error code table.
  4. Python (FastAPI) — reference folder layout and wiring patterns.
  5. Go (chi) — reference layout with internal/ and chi routing.
  6. Python and Go comparison — when each stack tends to fit.
Section titled “Related Library Guides”