Resources, Nouns & HTTP Methods
You'll learn to
- -Model an API around resources (nouns) rather than actions (verbs), and choose the right HTTP method for each operation
- -Apply consistent, plural resource naming that scales to nested and related resources
REST's foundational idea is that a URL identifies a resource - a noun - and the HTTP method describes the action taken on it. This sounds simple and is the single most common thing REST APIs get wrong under real-world pressure: it is very tempting to design action-shaped endpoints like `/getUser` or `/createOrder` instead of resource-shaped ones, especially for engineers coming from an RPC-style background.
Nouns, Not Verbs
# RESTful: the URL is a noun, the method carries the verb
GET /users/42 # fetch user 42
POST /users # create a new user
DELETE /users/42 # delete user 42
# Action-oriented (avoid in REST APIs): the verb leaks into the URL
GET /getUser?id=42
POST /createUser
POST /deleteUser?id=42The RPC-style version works, technically, but it throws away everything REST gives you for free: HTTP caching assumes GET requests are safe and idempotent, and `/getUser?id=42` vs `/users/42` looks identical to a cache or a browser, but the RESTful version composes predictably (every resource follows the same pattern) while the action-style version needs a new convention invented for every new capability.
The Core HTTP Methods
- -GET: retrieve a resource. Safe (no side effects) and idempotent (calling it twice has the same effect as once).
- -POST: create a new resource, or trigger a non-idempotent action. Not safe, not idempotent.
- -PUT: replace a resource entirely. Idempotent - sending the same PUT twice leaves the resource in the same state.
- -PATCH: partially update a resource. Not necessarily idempotent, depending on how the patch is expressed.
- -DELETE: remove a resource. Idempotent - deleting an already-deleted resource is still "deleted."
Plural Nouns, Consistently
Use plural resource names (`/users`, not `/user`) even for a single-item fetch (`/users/42`) - this keeps the pattern uniform: the collection is always plural, and an individual resource is the collection plus an identifier. Mixing singular and plural forms across an API (`/user/42` here, `/orders` there) is a small inconsistency that adds up to real friction for every client integrating against more than one endpoint.
A fast self-check for any endpoint you design: could you describe it as "[HTTP method] the [noun] resource(s)"? If the natural description needs a verb in the URL to make sense ("get the user" is fine; "get-active-user" is a smell), that is a signal the design has drifted toward RPC-style.
You see a proposed endpoint `POST /users/42/activate` to activate a user account. Is this good REST design?
"No, that's bad - it should be `POST /activateUser?id=42` instead."
"It's actually a reasonable, common REST pattern - `activate` here is being treated as a sub-resource or action attached to a specific user (`/users/42/activate`), not a verb baked into the base resource name. This is different from `/activateUser`, which puts the action ahead of the resource in the URL itself. As long as it's scoped under the specific resource being acted on, this kind of action endpoint is a defensible escape hatch for operations that don't map cleanly to plain CRUD."
What is the core problem with action-oriented endpoints like `/getUser` or `/createOrder`?
Design Hello, API World in the API Design Lab's REST Foundations act.