Saltar al contenido
AKOS
Todos los packs
StableBackendrest

REST API Design

Operationalizes REST API design: resource modeling, HTTP verb/status-code semantics, versioning, and pagination — the practical subset that makes APIs predictable and easy to consume.

resthttpapi-designpaginationversioningstatus-codes

Principios

  • · RS1 — URLs identify resources (nouns); actions are expressed via HTTP method, not verbs in the path.
  • · RS2 — Status codes are used correctly and consistently: 200/201/204 success variants, 400/401/403/404/409/422 client errors, 500 server errors.
  • · RS3 — GET/PUT/DELETE are truly idempotent; POST is used for non-idempotent creation/actions.
  • · RS4 — List endpoints support pagination (cursor or offset) with sane default and maximum page sizes.
  • · RS5 — Breaking changes are versioned (URL path or header-based), with old versions supported through a deprecation window.

Patrones

  • · URL with a verb (/createOrder, /getUserById) → refactor to noun + method (POST /orders, GET /users/:id).
  • · Endpoint always returning 200 even on failure with an error field in the body → fix status codes, clients shouldn't have to parse the body to know if it failed.
  • · Unbounded list endpoint → add pagination before it becomes a production incident.
  • · Inconsistent response shape across endpoints ({data: ...} here, raw object there) → standardize the envelope.

Riesgos

  • · RPC-in-REST-clothing — /api/doThing POST endpoints ignoring resource/verb conventions entirely.
  • · Always-200 — every response returns 200 OK with a {success: false, error: "..."} body, forcing clients to parse bodies to detect failure.
  • · Unbounded lists — GET /items returning the entire table with no pagination, a latent incident.
  • · Inconsistent envelopes — some endpoints return raw arrays, others {data: [...]}, others {results: [...], items: [...]} interchangeably.
  • · Silent breaking changes — modifying an existing endpoint's response shape without versioning, breaking every consumer without warning.

Checklist

  • [ ] URLs are nouns; verbs expressed via HTTP method. (RR1)
  • [ ] Status codes match actual outcome. (RR2)
  • [ ] List endpoints paginated with max page size. (RR3)
  • [ ] Versioning strategy explicit for breaking changes. (RR4)
  • [ ] Consistent response envelope across the API. (RR5)
  • [ ] Error responses have machine-readable code + message. (RR6)

Fuentes

En la bibliografía AKOS

Este pack cita las siguientes fuentes registradas en el índice bibliográfico:

Explorar todas las fuentes →