Resources, Not Actions
A RESTful API models URLs around resources (nouns), and uses HTTP methods to express the action — rather than encoding the verb into the URL itself. /users is a resource; GET, POST, PUT, and DELETE against it are the actions.
Standard REST Conventions
| Method + URL | Action |
|---|---|
| GET /users | List all users |
| GET /users/:id | Get a single user |
| POST /users | Create a new user |
| PUT /users/:id | Replace a user entirely |
| PATCH /users/:id | Partially update a user |
| DELETE /users/:id | Delete a user |
A Bad vs Good URL Design
# Avoid: verbs baked into the URL
POST /createUser
GET /getUserById?id=42
# Prefer: resources + HTTP methods
POST /users
GET /users/42Nested Resources
When one resource clearly belongs to another, nest it in the URL: /users/42/orders lists orders belonging to user 42. Avoid nesting more than one or two levels deep — it quickly becomes unwieldy.
Choosing the Right Status Code
| Situation | Status Code |
|---|---|
| Successful GET | 200 OK |
| Successful POST creating a resource | 201 Created |
| Successful DELETE | 204 No Content |
| Invalid request data | 400 Bad Request |
| Not authenticated | 401 Unauthorized |
| Authenticated but not allowed | 403 Forbidden |
| Resource does not exist | 404 Not Found |
PUT vs PATCH
PUT conventionally replaces the entire resource — fields you omit are expected to be reset. PATCH updates only the fields provided, leaving everything else untouched. Many real-world APIs use PATCH more often than strict REST purism would suggest, since it matches how forms actually submit partial edits.
Best Practice
Version your API from the start (e.g. /api/v1/users) — it costs almost nothing upfront and gives you a clean path to make breaking changes later without disrupting existing clients.