REST (Representational State Transfer) is the architectural style used by most web APIs — but the name “REST API” is applied inconsistently, and many so-called REST APIs violate the original design principles. Here is what REST actually means and why some of those principles matter.
The Core Principles
Resource-oriented: APIs should expose resources (nouns), not operations (verbs). GET /users/123 is REST; GET /getUser?id=123 is RPC-over-HTTP, not REST. HTTP methods have meaning: GET (read, safe, idempotent), POST (create), PUT (update/replace, idempotent), PATCH (partial update), DELETE (remove). Using POST for everything ignores the protocol semantics. Stateless: each request contains all information needed — no session state on the server between requests. Status codes are meaningful: 200 (OK), 201 (Created), 400 (Bad Request — client error), 401 (Unauthorized), 403 (Forbidden), 404 (Not Found), 500 (Server Error). Returning 200 with {“error”: “not found”} in the body is a REST anti-pattern.
URL Design
Resources are plural nouns: /users, /orders, /products. Nested resources express relationships: /users/123/orders (orders belonging to user 123). Avoid verbs in URLs: /users/123/activate is wrong; PATCH /users/123 {“active”: true} is better. Use query strings for filtering and sorting: /products?category=books&sort=price&order=asc.
The Status Code Everyone Gets Wrong
404 means the resource does not exist, not that the search returned no results. GET /search?q=nothing returning 404 is wrong — return 200 with an empty results array. 422 (Unprocessable Entity) is the correct status for validation failures, not 400 (which means the request was malformed) or 200.
When Not to Use REST
GraphQL is better when clients need flexibility in what data they fetch (avoiding over-fetching). gRPC is better for internal service-to-service communication (schema-first, efficient binary protocol). REST is ideal for public APIs, mobile backends, and any situation where simplicity and wide client support matter.
