REST API

The parts that matter day to day

Resources, not actions. The URL names a thing — /orders, /orders/42 — and the method names the operation. GET /orders/42 reads it, DELETE /orders/42 removes it. Endpoints like /getOrderById work fine but are not what REST means.

Statelessness. The server keeps no memory of previous requests, so every call carries its own authentication, usually a bearer token in the Authorization header. That is what allows any server behind a load balancer to answer any request.

Status codes carry meaning. 200 succeeded, 201 created, 400 the request was malformed, 401 not authenticated, 403 authenticated but not allowed, 404 no such resource, 429 rate limited, 500 the server broke. An API that returns 200 with {"error": ...} in the body forces every client to parse before it can tell success from failure.

Idempotency. GET, PUT and DELETE should produce the same end state whether sent once or five times; POST normally does not, which is why retrying a failed payment request needs an idempotency key.

The misconception

Most things called REST APIs are not REST in the strict sense. Roy Fielding's definition includes hypermedia — responses that link to the next available actions — and almost nothing implements it. What the industry actually means by "REST API" is JSON over HTTP with sensible URLs and verbs. That is fine, and worth knowing when a purist objects.

When something else fits better

GraphQL lets a client ask for exactly the fields it needs in one request, which suits screens that would otherwise make six calls; the cost is caching and complexity. Webhooks invert the direction for events you would otherwise have to poll for. And for versioning, the honest advice is to decide early — putting /v1/ in the path costs nothing now and saves a painful migration when a response shape has to change.