Stackbook Logo
architecture-descriptionestablished · low operational burden

API Design (RESTful)

Also known as: rest-api-design, api-guidelines, rest-best-practices

Intent

Design consistent, evolvable, developer-friendly REST APIs using standard conventions.

Problem

Inconsistent APIs: /getUser vs /users/{id}, 200 on error, no pagination. Clients break, developers frustrated.

Forces

  • •Multiple teams designing APIs independently
  • •Clients: web, mobile, partners — different needs
  • •Evolution: add fields, deprecate, version
  • •Standards: HTTP semantics, JSON, RFCs

Solution

✓ When to Use

  • •Any team building REST APIs
  • •Public or partner APIs
  • •Multiple consumers (web, mobile, third-party)

✗ When Not to Use

  • •Internal RPC (gRPC better)
  • •GraphQL APIs (different paradigm)
  • •Simple internal tools

Pros

  • +Consistency: predictable, learnable
  • +Evolvability: additive changes safe
  • +Tooling: OpenAPI → clients, docs, mocks, tests
  • +Caching: HTTP semantics enable CDN, browser cache

Cons

  • −Over-fetching/under-fetching (GraphQL solves)
  • −Chatty: multiple round-trips for related data
  • −Versioning overhead
  • −HTTP limitations: no streaming, limited methods

Cost Profile

Infrastructure

Low — design discipline, linting

Operational

Low — version management

Cognitive

Medium — conventions, trade-offs

Failure Modes

  • Inconsistent naming: /getUser, /userList, /users

  • Breaking changes without version: field removed

  • Error as 200: {success: false, error: ...}

  • No pagination → 10k items returned

  • Verb in URL: /createUser, /deleteOrder

Real-World Examples

Alternatives

  • graphql
  • grpc
  • tRPC
  • rpc

Related Patterns

  • api-versioning
  • api-gateway
  • consumer-driven-contracts
  • openapi
  • pagination
  • idempotency-key

Competency Domains

distribution communicationeconomics evolutiondeploymentreliability ops