REST API Basics
3 min read · Published
Table of contents
A REST API lets programs talk to a server over HTTP by reading and changing resources: users, orders, posts. "REST" (Representational State Transfer) is an architectural style described by Roy Fielding in 2000. In practice, "a REST API" usually means: resources identified by URLs, standard HTTP methods, stateless requests, and JSON bodies.
Resources and URLs
Model your API around nouns, not verbs:
GET /users list users
POST /users create a user
GET /users/42 read user 42
PUT /users/42 replace user 42
PATCH /users/42 partially update user 42
DELETE /users/42 delete user 42
GET /users/42/orders orders belonging to user 42
Use plural nouns, lowercase paths and hyphens or underscores consistently. Avoid /getUser or /deleteOrder; the method already says what to do.
HTTP methods and their properties
| Method | Purpose | Safe | Idempotent |
|---|---|---|---|
| GET | Read | yes | yes |
| POST | Create / trigger an action | no | no |
| PUT | Replace | no | yes |
| PATCH | Partial update | no | usually no |
| DELETE | Remove | no | yes |
Safe means it does not change server state. Idempotent means repeating the request has the same effect as sending it once, which makes retries after timeouts safe. For non-idempotent POSTs, many APIs accept an Idempotency-Key header.
Requests and responses
POST /users HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Bearer eyJhbGciOi...
{"name":"Ada","email":"ada@example.com"}
HTTP/1.1 201 Created
Content-Type: application/json
Location: /users/42
{"id":42,"name":"Ada","email":"ada@example.com"}
The body is JSON. Format and check payloads with the JSON Formatter while debugging.
Status codes
Return meaningful status codes: 200, 201, 204 for success; 400, 401, 403, 404, 409, 422, 429 for client errors; 500 and 503 for server problems. See Common HTTP Status Codes and the searchable status code reference.
Query parameters: filtering, sorting, pagination
GET /orders?status=paid&sort=-created_at&limit=20&cursor=eyJpZCI6MTAwfQ
- Filtering:
?status=paid. - Sorting:
?sort=-created_at(a leading minus for descending is a common convention). - Pagination:
limitplusoffset, or better, an opaque cursor that stays correct when new rows arrive.
Remember to percent-encode values that contain spaces or reserved characters; try the URL Encoder.
Authentication
- API keys in a header: simple, for server-to-server use.
- Bearer tokens, often JWTs:
Authorization: Bearer <token>. - OAuth 2.0 for delegated access on behalf of users.
Always use HTTPS. Never put secrets in URLs, since they end up in logs and browser history.
Statelessness
Each request must contain everything the server needs to handle it (credentials, parameters). The server does not remember earlier requests. This makes scaling easy: any server instance can answer any request.
Versioning
Breaking changes need a new version: /v1/users in the path, or a header such as Accept: application/vnd.example.v2+json. Prefer additive, backwards-compatible changes (new optional fields) so versions change rarely.
Error responses
Use a consistent shape:
{ "error": { "code": "not_found", "message": "User 42 does not exist" } }
Caching and conditional requests
GET responses can be cached. ETag plus If-None-Match lets a client revalidate cheaply: the server answers 304 Not Modified with no body when nothing changed.
Timestamps and IDs
Use ISO 8601 UTC strings (2026-11-15T10:30:00Z) or Unix time, never ambiguous local formats; see Understanding Unix Timestamps. For identifiers, UUIDs from the UUID Generator avoid guessable sequential IDs.
Common mistakes
- Verbs in URLs and mixing singular and plural.
- Returning 200 for errors.
- No pagination on list endpoints.
- Exposing database internals (auto-increment IDs, column names) as your public contract.
- Not validating input on the server.
Try it
You can call any public API from a terminal:
curl -s https://api.github.com/repos/vercel/next.js | head -c 400
Paste the response into the formatter to explore the structure.
Related tools
JSON Formatter
Format, beautify and minify JSON with custom indentation.
HTTP Status Code Reference
Searchable reference of HTTP status codes with explanations.
URL Encoder
Percent-encode text for safe use in URLs.
JWT Decoder
Decode JWT header, payload and expiry. Never leaves your browser.
FAQ
Is REST a protocol?
No. REST is an architectural style. Most REST APIs use HTTP and JSON, but REST itself does not mandate either.
PUT or PATCH?
PUT replaces a whole resource; PATCH applies a partial change.
What does idempotent mean?
Repeating the same request has the same effect as sending it once. GET, PUT and DELETE are idempotent; POST usually is not.
Keep reading
- Common HTTP Status Codes Every Developer Should Know
The HTTP status codes you will meet most often, what they mean and which one to return from your API in common situations.
- What Is JSON and How Does It Work?
Learn what JSON is, its syntax rules, data types, common mistakes and how to read and write it in JavaScript and Python.