REST API Design for CRUD Resources¶

Now we expose our CRUD operations over HTTP. Good API design makes clients easy to write and endpoints easy to reason about.

The Standard Resource Endpoints¶

For a task resource:

GET    /tasks          → list tasks
POST   /tasks          → create a task
GET    /tasks/:id      → read one task
PUT    /tasks/:id      → replace a task
PATCH  /tasks/:id      → partially update a task
DELETE /tasks/:id      → delete a task

This is the collection + item pattern. Memorize it — almost every resource in your app follows it.

Nesting for Relationships¶

When a resource belongs to another, nest it:

GET  /users/:id/tasks      → tasks owned by a user
POST /users/:id/tasks      → create a task for that user

Don't nest more than one level deep (/users/1/tasks/2/tags/3 is a smell). Past one level, use query parameters or top-level routes.

Plural Nouns, Consistently¶

✅ /tasks, /users, /tags
❌ /task, /getUser, /tagList

Pick plural nouns and stay consistent across the whole API.

Versioning¶

Public APIs change. Version from day one:

/api/v1/tasks

It costs nothing now and saves you from breaking clients later.

Shape Your Responses¶

Return consistent JSON. A common envelope for lists:

json

4 lines

1{
2  "data": [ { "id": "...", "title": "..." } ],
3  "meta": { "page": 1, "pageSize": 20, "total": 137 }
4}

For a single item, return the object (or wrap it in { "data": {...} } — just be consistent).

Design Checklist¶

Nouns in URLs, verbs as HTTP methods.
Plural, consistent resource names.
One level of nesting maximum.
Versioned base path.
Predictable response and error shapes.