Skip to content
API Design Learn/REST Resource Modeling
Browsing as a guest. Sign in to save your progress and earn XP as you complete chapters.

Resources, Nouns & HTTP Methods

5 min read

You'll learn to

  • -Name things in the URL (nouns) and put the action in the HTTP method (the verb)
  • -Explain safe and idempotent in plain words, and see them by running POST, PUT and DELETE twice
  • -Apply plural, consistent resource names, and know how to handle an action that is not plain create, read, update or delete

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.

An API (application programming interface) is a set of requests one program can send to another. When you design a web API in the REST style, the foundational idea is that a URL identifies a resource, which is a thing the API exposes, such as a user or an order, and the HTTP method says what you want to do with it. This sounds simple, and it is the thing REST APIs most often get wrong under pressure. It is very tempting to build action-shaped endpoints like /getUser or /createOrder, especially if you come from an RPC (remote procedure call, "call a function over the network") background.

An Analogy: The Library

In a library, each book has a catalog number, and the number is the book's address. What you can do with it is a short list: look at it, borrow it, return it. You would not invent a different desk for "look at book 42" and another for "look at book 43". In a REST API the URL is the catalog number (/books/42) and the HTTP method is the short list of things you can do.

Nouns, Not Verbs

Resource-oriented (RESTful) vs. action-oriented (RPC-style)
# 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=42

The action-style version works, technically. But it throws away what REST gives you for free. Every resource follows the same pattern, so a developer who learns /users already knows how /orders behaves. HTTP caches also assume that GET requests are safe to repeat. With action-style URLs, each new capability needs a new convention invented for it.

The Core HTTP Methods

Two words matter here. A request is safe if it has no side effects: it only reads. A request is idempotent if doing it twice leaves the same result as doing it once. Think of pressing a lift call button: the second press does not summon a second lift.

  • -GET retrieves a resource. Safe, and idempotent.
  • -POST creates a new resource, or triggers an action. Not safe, and not idempotent: sending it twice creates two things.
  • -PUT replaces a resource entirely. Idempotent: sending the same PUT twice leaves the same state.
  • -PATCH changes part of a resource. Not necessarily idempotent, depending on how the change is written.
  • -DELETE removes a resource. Idempotent: deleting something already deleted still leaves it deleted.

Run the demo to see the difference. It sends POST twice, PUT twice and DELETE twice against a small in-memory store.

Press Run: POST twice makes two users, PUT twice makes one change, DELETE twice ends the same

Plural Nouns, Consistently

Use plural names (/users, not /user) even for a single item (/users/42). The collection is always plural, and one member is the collection plus an identifier. Mixing singular and plural across an API is a small inconsistency that adds friction for every client.

What About an Action That Is Not Create, Read, Update or Delete?

Sometimes the operation does not fit the four basic verbs, such as activating an account. First ask whether it is really a change to a field: PATCH /users/42 with {"status": "active"} is often the cleanest answer. If the operation has effects beyond changing a field, such as sending an email or charging a card, a named action under the resource, like POST /users/42/activation, is acceptable when used sparingly and still named with a noun.

A fast self-check: can you describe the endpoint as "[HTTP method] the [noun] resource"? If the URL needs a verb to make sense, as in get-active-user, the design has probably drifted toward RPC.

Interview Signal

You see a proposed endpoint POST /users/42/activate to activate a user account. Is this good REST design?

Weak Answer

"No, that's bad - it should be POST /activateUser?id=42 instead."

Strong Answer

"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."

Check Yourself1 / 5

What is the core problem with action-oriented endpoints like /getUser or /createOrder?

Ready to Build This?

Design Hello, API World in the API Design Lab's REST Foundations act.

Discussion0

Join the Discussion

Sign in to leave comments, reply to others, or like insights.

Sign In to ScaleDojo

No comments yet. Be the first to start the thread!