tool / 53

REST Conventions

Practical conventions for REST APIs that age well — URLs, methods, statuses, common patterns.

All local

27/27

URLs5

Use nouns, not verbs

GET /users — not /getUsers. The HTTP method is the verb.

Plural collections

GET /users instead of /user. Singular for a single thing: GET /users/42.

Lowercase, hyphenated

/blog-posts — not /BlogPosts or /blog_posts. Lowercase and hyphens read best.

Nest sparingly

Up to one level: /users/42/posts. For deeper, use query params: /posts?author=42.

Versioning

Put the major version in the path: /v1/users. Or in a header. Pick one and be consistent.

Methods5

GET

Read. Safe and idempotent. Never has a body. Cacheable.

POST

Create — or any non-idempotent operation. Returns 201 with Location header.

PUT

Replace the whole resource. Idempotent — same request twice = same result.

PATCH

Partial update. Send only the fields to change.

DELETE

Remove. Idempotent — second delete returns 404 or 204.

Status10

200 OK

Successful read or update. Body required.

201 Created

Resource created. Include Location header pointing to the new thing.

204 No Content

Success with no body — typical for DELETE or empty PUT.

400 Bad Request

Client sent something malformed. Include details in the body.

401 Unauthorized

Missing or invalid auth. Always include WWW-Authenticate.

403 Forbidden

Authenticated but not allowed. No retry will help.

404 Not Found

Resource doesn't exist. Or you're hiding 403s for security.

409 Conflict

Resource is in a state that prevents the operation. Duplicates, version mismatch.

422 Unprocessable Entity

Request was well-formed but validation failed. List the field errors.

429 Too Many Requests

Rate limited. Always include Retry-After.

Patterns7

Pagination

Use ?page=2&size=20 or cursor: ?after=abc&limit=20. Include total count when affordable.

Filtering

Use query params: ?status=active&country=GB. Multi-value via repeated key or comma.

Sorting

?sort=name or ?sort=-created_at (minus = descending).

Sparse fieldsets

?fields=id,name lets clients ask for only what they need.

Idempotency keys

POSTs that must run exactly once should accept Idempotency-Key header.

HATEOAS

Include _links to related and next-step resources. Optional but powerful for discoverability.

Errors are JSON

Return { "error": "...", "details": [...] }. Match status code to type. Be consistent.