REST API Cheat Sheet

REST is an architectural style for exposing application capabilities as networked resources. The shortest practical summary is this: model the important nouns in your system, move them over HTTP with predictable semantics, and make the interface boring enough that clients can guess how it behaves.

Model resources, not controller actions

A REST API usually centres on resources such as /users, /orders, /invoices, or /devices. The path identifies what the client is working with. HTTP methods express what kind of change is being requested.

• GET reads a resource or collection.
• POST creates a new subordinate resource or triggers a non-idempotent action.
• PUT replaces a resource representation.
• PATCH changes part of a resource.
• DELETE removes a resource.

This matters because clients, caches, proxies, and tooling all rely on those semantics.

Idempotency is part of correctness

Idempotency means repeating the same request has the same effect as doing it once. GET, PUT, and DELETE are intended to be idempotent. POST usually is not. This becomes operationally important during retries. If a network timeout causes the client to resend a request, the server should not create accidental duplicates unless the contract explicitly allows it.

For create-like operations that must survive retries safely, many APIs add idempotency keys.

Statelessness makes scaling easier

A REST API is typically stateless at the request layer. Each request carries the authentication, authorisation context, and request data it needs. That simplifies horizontal scaling because any healthy server can handle any request without recovering hidden session state first.

Stateless does not mean the application has no state. It means the server does not rely on per-client conversational state between requests.

Use HTTP features properly

REST works best when it respects HTTP instead of tunnelling everything through POST. Status codes should communicate outcomes clearly: 200 for success, 201 for creation, 204 for success without a body, 400 for bad requests, 401 for unauthenticated, 403 for forbidden, 404 for missing resources, and 409 for conflicts.

Caching headers such as Cache-Control, ETag, and If-None-Match are also part of the design, not optional decoration. For read-heavy APIs they can remove a surprising amount of backend load.

Collections need predictable controls

Real APIs need pagination, filtering, and sorting. These should follow consistent conventions, usually through query parameters. Error payloads should also be structured consistently so clients can distinguish validation problems from permission issues or rate limiting.

Versioning is a last resort, not the first feature to add. Many APIs evolve successfully for a long time through additive changes.

Where REST fits and where it does not

REST is strongest when you want a uniform interface, straightforward caching, and resource-oriented workflows that many clients can understand easily. It is less elegant for highly stateful interactions, deeply nested client-specific data shapes, or workflows that are better represented as asynchronous jobs.

A good REST API feels unsurprising. That is not a weakness. Predictability is the feature.