REST API design cheat sheet

Resources and methods

GET /users

List users

GET /users/42

One user

POST /users

Create a user

PATCH /users/42

Change part of a user

DELETE /users/42

Delete a user

GET /users/42/orders

The orders of one user

Use plural nouns for names and let the method be the verb.

Lists

?limit=20&cursor=abc

Page by a cursor (best for large, changing data)

?page=2&per_page=20

Page by number (simple)

?status=active&sort=-created_at

Filter and sort (minus means newest first)

{ data: [], next_cursor: "..." }

A list answer that tells the client how to continue

Responses

201 + Location header

After creating something

204

Done, nothing to send back

422 or 400

The data failed validation

{ error: { code, message, fields } }

One error shape for the whole API

Safe retries and limits

Idempotency-Key: <unique value>

Lets a client retry a POST without creating twice

429 + Retry-After

Rate limit reached; wait this long

X-RateLimit-Remaining

How many calls are left

Versions and security

/v1/users

Put the version in the address (simple and visible)

Authorization: Bearer <token>

Send credentials in a header, never in the address

HTTPS only

Never serve an API over plain HTTP

Validate every input on the server

Never trust the client