REST
REST (Representational State Transfer) is an architectural style for APIs over HTTP. You model your domain as resources with stable URLs (/orders/42), and act on them with the standard HTTP methods (GET, POST, PUT, PATCH, DELETE). Each request is stateless, carrying everything the server needs, and responses can be cached. Most public APIs you will ingest from (Stripe, GitHub, Salesforce, Shopify) are REST APIs returning JSON.
The term comes from Roy Fielding’s 2000 PhD thesis. In practice, “RESTful” usually means “resource-oriented JSON over HTTP”, not every constraint Fielding described.
Resources and methods
- One collection, /orders, holds two orders. Each order has its own URL. The method says what to do with it.
- GET /orders lists the collection: 200 with a JSON array. Safe: nothing changes on the server.
- POST /orders creates a new order. The server picks the ID and answers 201 Created with a Location header pointing at it.
- GET /orders/42 reads one resource by its URL: 200 and the order as JSON.
- PATCH /orders/42 changes only the fields you send. The order is now shipped.
- DELETE /orders/42 removes it. 204 No Content: success, with no body to return.
- Asking for it again gets 404 Not Found. The URL is the same; the resource is gone.
| Request | Meaning | Success | Idempotent |
|---|---|---|---|
GET /orders?status=shipped&limit=50 |
List orders, filtered | 200 | yes |
GET /orders/42 |
Read one order | 200, or 404 | yes |
POST /orders |
Create an order | 201 + Location: /orders/43 |
no |
PUT /orders/42 |
Replace order 42 | 200 or 204 | yes |
PATCH /orders/42 |
Change some fields | 200 | not necessarily |
DELETE /orders/42 |
Delete it | 204 | yes |
GET /users/7/orders |
Orders belonging to user 7 | 200 | yes |
URLs are nouns. The verb is the HTTP method. /getOrder?id=42 or POST /deleteOrder are RPC in disguise.
Try it
JSONPlaceholder is a free fake REST API you can practice on. Writes are accepted and echoed back but not stored.
API=https://jsonplaceholder.typicode.com
curl -s $API/users/1 | jq '.name, .email' # GET one resource
curl -s "$API/posts?userId=1" | jq length # GET a filtered collection
curl -s -i -X POST $API/posts \
-H "Content-Type: application/json" \
-d '{"title":"hello","userId":1}' # POST: 201 Created + the new id
curl -s -o /dev/null -w "%{http_code}\n" -X DELETE $API/posts/1 # DELETE: 200Design rules that age well
- Use status codes properly. 400 for bad input with a JSON error body, 401 vs 403, 404, 409 for conflicts, 429 with
Retry-Afterfor rate limits. A consistent error format such as RFC 9457 “Problem Details” helps clients. - Paginate every list. Prefer cursor pagination (
?after=ord_123) over?page=7: offsets skip or repeat rows when data changes between requests, which is exactly what happens during an incremental sync. - Support incremental reads. A filter like
?updated_since=2026-01-01T00:00:00Zlets pipelines fetch only what changed. - Make retries safe. Accept an
Idempotency-Keyheader onPOSTso a retried payment isn’t charged twice. - Version deliberately.
/v1/...in the path or a header. Add fields freely; never rename or remove them without a new version. - Describe it with OpenAPI. An OpenAPI 3.1 (or 3.2, released 2025) document gives you docs, client generation, mocks and request validation for free.
REST vs GraphQL vs gRPC
| REST | GraphQL | gRPC | |
|---|---|---|---|
| Shape | Many resource URLs | One endpoint, client writes a query | Service methods defined in .proto |
| Payload | JSON (usually) | JSON | Protobuf (binary) |
| Transport | HTTP/1.1, 2 or 3 | HTTP | HTTP/2 |
| HTTP caching | Natural (GET + ETag) | Hard (mostly POST) | No |
| Streaming | SSE, webhooks | Subscriptions | Built in, both directions |
| Best for | Public APIs, CRUD, integrations | Front-ends with varied data needs | Internal service-to-service, low latency |
Common mistakes
- Returning 200 with
{"error": ...}in the body. Clients and monitoring can’t tell it failed. - Unbounded list endpoints that return 2 million rows in one response.
- Chatty APIs that need 20 calls to render one screen. Offer an
?expand=option, a dedicated endpoint, or consider GraphQL. - Breaking changes without a version, which silently breaks every downstream pipeline.
Learning Resources
Books
- Designing Web APIs: Jin, Sahni, Shevat
- API Design Patterns: JJ Geewax, based on Google’s API design rules
Articles and references
- Fielding’s dissertation, chapter 5: REST
- Microsoft REST API Guidelines and Google API Improvement Proposals
- Zalando RESTful API Guidelines
- OpenAPI Specification
- RFC 9457: Problem Details for HTTP APIs
See also: HTTP, Web frameworks.