Most RESTful APIs aren't really RESTful

Original Article ↗ Hacker News Discussion ↗

Terminology & Semantic Drift

  • Many argue that “REST API” now colloquially means “HTTP+JSON API with CRUD-ish verbs and maybe OpenAPI,” not Fielding’s original REST.
  • Some prefer terms like “HTTP API”, “REST-like”, or “REST-ish” to avoid arguing about correctness.
  • Several note this is similar to how terms like Agile, DevOps, or OOP have drifted from original definitions.

HATEOAS and “True” REST

  • Core REST constraints (notably HATEOAS and media types) are rarely implemented.
  • Critics say HATEOAS adds payload bloat, complexity, and requires hypermedia-aware clients that almost never exist outside browsers.
  • Supporters claim it improves evolvability, discoverability, and decoupling, but mostly when the client is generic (browser, API browser, LLM) rather than a bespoke app.

HTTP APIs in Practice (RPC, JSON, GraphQL)

  • Common real-world pattern: RPC-like JSON over HTTP (often POST-only or GET+POST) plus status codes.
  • Many see this as pragmatic: easy to implement, test (curl/httpie), and integrate with OpenAPI, codegen, and tooling.
  • Some mix “resource-ish” endpoints for data with explicit action endpoints (e.g. /vote, /search) where REST semantics fit poorly.
  • GraphQL is praised for discoverability and flexible querying, but criticized for performance, complexity, and bypassing HTTP semantics.

HTTP Verbs, Status Codes, and Security

  • Strong disagreement over strict verb usage:
    • Purists want GET safe/idempotent and non-mutating; warn about crawlers, prefetching, caching, CSRF assumptions, SameSite cookies, etc.
    • Others happily mutate via GET or use POST for reads when URLs/filters get complex.
  • Status codes are widely misused; teams bike-shed on 4xx vs 5xx, PUT vs PATCH, etc., or collapse everything to 200 with JSON error fields.
  • Some argue strict HTTP semantics aid proxies, caching, rate limiting; others say it adds little over application-level error handling.

REST, UI, and Clients (Humans vs Machines)

  • One camp: REST/HATEOAS fundamentally targets human-driven hypermedia (the Web itself); browsers + people are the “evolvable client.”
  • Machine clients generally rely on out‑of‑band knowledge (docs, schemas, generated code), so full HATEOAS brings little value and is hard to use.
  • AI/LLM agents are mentioned as a possible future where hypermedia-style APIs and richer schemas could matter again.

Experiences & Trade-offs

  • Several report trying to build fully RESTful/HATEOAS APIs and abandoning it: too much server and client complexity, little actual use of links.
  • For most business apps, teams optimize for feature delivery speed, a workable contract (often OpenAPI), and predictable behavior, not academic purity.
  • Consensus thread: understand REST’s ideas (statelessness, resource thinking, HTTP semantics), but design “HTTP APIs” pragmatically for your consumers.