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
Tip: the highlighter is on - just select any text below to mark it. Use the highlighter button up top to change color or turn it off. Highlights are saved on this device only. Log in to save them to your account instead.
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.