REST (Representational State Transfer)
debt(d7/e7/b7/t7)
Closest to 'only careful code review or runtime testing' (d7). Tools like spectral and openapi-validator can catch some violations (wrong status codes, verbs in URLs) but most REST violations (statefulness, missing HATEOAS, GET with side effects) require human review of API design.
Closest to 'cross-cutting refactor across the codebase' (e7). Fixing REST violations means reshaping URL structures, HTTP methods, and status codes across every endpoint — clients depending on the API must also change. Not a one-line patch despite the quick_fix description.
Closest to 'strong gravitational pull' (b7). The API shape defines how every consumer interacts with the system; applies broadly to web/api contexts and shapes every new endpoint added.
Closest to 'serious trap' (t7). The misconception is explicit: developers believe JSON-over-HTTP equals REST, when true REST requires statelessness, uniform interface, and HATEOAS. The 'obvious' interpretation contradicts the actual architectural constraints.
Also Known As
TL;DR
Explanation
REST (Roy Fielding, 2000) defines six constraints: client-server, stateless, cacheable, uniform interface, layered system, and optional code-on-demand. Practical REST APIs use HTTP verbs semantically (GET retrieves, POST creates, PUT/PATCH updates, DELETE removes), identify resources via URLs, and communicate state via standard status codes (200, 201, 400, 401, 403, 404, 422, 500). True RESTfulness (HATEOAS) is rarely fully implemented — most APIs are REST-like (sometimes called Level 2 of the Richardson Maturity Model). Use consistent status codes and error bodies across all endpoints.
Common Misconception
Why It Matters
Common Mistakes
- Verbs in URLs: POST /getUser, GET /createOrder — use nouns and HTTP methods correctly.
- Stateful REST: storing session data server-side between requests — each request must be self-contained.
- Using GET for state-changing operations — GET must be safe and idempotent; use POST/PUT/PATCH/DELETE.
- Returning HTTP 200 for errors — use the appropriate 4xx/5xx status code.
Code Examples
// RPC-style URLs with wrong HTTP methods:
GET /api/getUser?id=1 // Wrong: verb in URL, should be GET /users/1
POST /api/deleteUser // Wrong: should be DELETE /users/1
GET /api/createOrder // Wrong: GET mutates state — must be POST /orders
POST /api/updateUserProfile // Wrong: should be PATCH /users/1/profile# Resource-oriented URLs + correct HTTP verbs
GET /users # list
POST /users # create
GET /users/{id} # read
PUT /users/{id} # full replace
PATCH /users/{id} # partial update
DELETE /users/{id} # delete
# PHP: return appropriate status codes
return response()->json($user, 201); // Created
return response()->json(null, 204); // No Content (DELETE)
return response()->json($errors, 422); // Unprocessable Entity