Resources, not actions
A REST API models your domain as resources addressed by URLs. A resource is a noun like an order or a user. You act on resources using HTTP verbs rather than inventing custom action names.
- GET reads a resource and never changes state.
- POST creates a new resource under a collection.
- PUT replaces a resource and PATCH updates part of it.
- DELETE removes a resource.
Shape the URLs
Use plural collection nouns and nest sparingly. A path like users then an id then orders reads naturally and stays predictable. Avoid putting verbs in paths because the verb already lives in the method.
Status codes and bodies
Return 2xx for success, 4xx when the client is at fault, and 5xx for server errors. Send a consistent JSON body with the resource on reads and a clear error object on failures. Include a location header when you create something.
Be predictable
Consistency beats cleverness. If pagination, filtering, and errors work the same way everywhere, clients learn the API once and reuse that knowledge across every endpoint.
Key idea
A good REST API maps resources to URLs and uses HTTP verbs and status codes so behavior is predictable across every endpoint.