$ curl -s https://api.shop.com/orders/42

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

$ curl -X DELETE https://api.shop.com/orders/42
One resource, six requests
REQUEST RESPONSE SERVER · /orders /orders/41status: paid/orders/42status: paid GET /orders 200 [41, 42] /orders/43status: new POST /orders{"sku":"A7"} 201 Location: /orders/43 GET /orders/42 200 {"status":"paid"} PATCH /orders/42{"status":"shipped"} 200 {"status":"shipped"} DELETE /orders/42 204 No Content GET /orders/42 404 Not Found status: shipped deleted
  1. One collection, /orders, holds two orders. Each order has its own URL. The method says what to do with it.
  2. GET /orders lists the collection: 200 with a JSON array. Safe: nothing changes on the server.
  3. POST /orders creates a new order. The server picks the ID and answers 201 Created with a Location header pointing at it.
  4. GET /orders/42 reads one resource by its URL: 200 and the order as JSON.
  5. PATCH /orders/42 changes only the fields you send. The order is now shipped.
  6. DELETE /orders/42 removes it. 204 No Content: success, with no body to return.
  7. 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: 200

Design 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-After for 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:00Z lets pipelines fetch only what changed.
  • Make retries safe. Accept an Idempotency-Key header on POST so 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

Articles and references

See also: HTTP, Web frameworks.