Designing REST APIs

REST is a set of conventions, not a spec. Following them makes your API predictable.

4 min read Level 2/5 #nodejs#rest#api

What you'll learn

Model resources and collections
Pick the right HTTP method
Use status codes correctly

REST isn’t strict — it’s a set of conventions. Follow them and any other dev can read your API at a glance.

Resources and Collections

Group endpoints by resource (noun, plural):

/api/users           ← the collection
/api/users/42        ← one user
/api/users/42/posts  ← that user's posts

Avoid verbs in URLs (/getUser 👎). The verb is the HTTP method.

Methods → Operations

Method	Operation	Idempotent?
`GET /users`	List	yes
`GET /users/42`	Read one	yes
`POST /users`	Create	no
`PUT /users/42`	Full replace	yes
`PATCH /users/42`	Partial update	(yes-ish)
`DELETE /users/42`	Delete	yes

Idempotent = the same request repeated has the same effect.

Status Codes That Matter

Code	Meaning
200	OK — successful GET/PATCH/PUT
201	Created — successful POST
204	No Content — successful DELETE
301 / 302	Redirect
400	Bad Request — invalid input
401	Unauthorized — no/bad auth
403	Forbidden — authed but not allowed
404	Not Found
409	Conflict — duplicate, version mismatch
422	Unprocessable — valid format, invalid data
429	Too Many Requests
500	Server Error
503	Service Unavailable

Use 401 for “who are you” and 403 for “I know you, you can’t do this”. A frequent confusion.

Response Shape

Be consistent. A common pattern:

// success
{ "data": { "id": 42, "name": "Ada" } }

// list
{ "data": [...], "pagination": { "next": "...", "total": 100 } }

// error
{ "error": { "code": "user_not_found", "message": "..." } }

Pick a shape, stick to it. Mixed shapes drive clients crazy.

Pagination

For large collections, never return all rows:

GET /users?limit=20&cursor=abc

Cursor-based > offset-based. Offset (?page=2) breaks when rows are inserted/deleted. Cursors are stable.

Versioning

Bake a version into the URL or a header. URL is more common:

/api/v1/users
/api/v2/users

Bump v when you make a breaking change. Don’t break v1 silently.

Don’t Over-REST

Some operations don’t map cleanly to verbs+nouns. POST /sessions (login) is fine. POST /users/42/activate is fine. RPC-style endpoints (POST /trigger-recompute) are fine when REST gets contorted. Pragmatism over purity.

CORS →