REST API Basics
REST = 'resources addressed by URL + state manipulated via HTTP verbs'. Not a strict spec, but these conventions cover 95% of real APIs.
1 credit
Verbs → intent
5 itemsGET
Read, idempotent, cacheableMust not cause side effects
POST
Create, or non-idempotent actionPUT
Replace whole resource, idempotentPATCH
Partial updateDELETE
Remove, idempotentStatus codes (common)
10 items200 OK
Success with body201 Created
POST that created a resource (return Location header)204 No Content
Success, nothing to return (DELETE / PATCH)400 Bad Request
Malformed input — client's fault401 Unauthorized
Not authenticated403 Forbidden
Authenticated but not allowed404 Not Found
Resource doesn't exist409 Conflict
State conflict (duplicate, stale version)429 Too Many Requests
Rate limited — include Retry-After header500 Internal Server Error
Your bug — log and fixResource naming
- Plural nouns: `/users`, not `/user` or `/getUsers`.
- Nest sparingly: `/users/42/posts` ok; `/users/42/posts/7/comments/3` is too deep.
- Filter via query: `GET /posts?author=42&status=published`.
- Version in the path: `/v1/users`. Or in a header — pick one and be consistent.
Gotchas
- Pagination: always use cursor-based (`?after=<id>`) for anything likely >10k rows. Offset pagination breaks on insert.
- Dates: always ISO 8601 UTC in responses (`2026-04-18T14:30:00Z`).
- Nulls vs omitted fields — pick a convention and document it.
- `PATCH` with JSON Merge Patch (RFC 7396) is the simplest partial-update format.