REST API

REST in practice — resources and verbs

Every "thing" your API operates on becomes a resource at a URL. Operations on it use HTTP methods. A user-management API might look like:

Method	URL	Action	Status code
GET	/users	List all users (paginated)	200
GET	/users/42	Get user 42	200 (or 404)
POST	/users	Create a new user	201 Created (with Location header)
PUT	/users/42	Replace user 42 entirely	200 or 204
PATCH	/users/42	Partial update of user 42	200 or 204
DELETE	/users/42	Remove user 42	204 No Content (or 404)
GET	/users/42/orders	List user 42's orders (sub-resource)	200

The pattern scales: any noun can be a resource. /orders, /orders/123, /orders/123/items, /orders/123/items/5. Every URL identifies one thing; every method does the standard operation on that thing.

REST vs alternatives

	REST	GraphQL	gRPC	SOAP
Transport	HTTP	HTTP (usually POST to /graphql)	HTTP/2 (mostly)	HTTP, SMTP, others
Schema	Optional (OpenAPI/Swagger)	Required (GraphQL SDL)	Required (Protocol Buffers)	Required (WSDL/XSD)
Body format	JSON usually	JSON	Protobuf binary	XML
Single endpoint	No — many URLs	Yes — one URL, queries pick fields	One URL per RPC method	One URL per service
Over-fetching	Common — fixed response shape	Eliminated — client picks fields	Less — typed schemas	Common
Caching (HTTP)	Excellent — Cache-Control works	Hard — POST to /graphql isn't cached	Custom — outside HTTP	Hard
Tooling	Mature — Postman, curl, OpenAPI ecosystem	Apollo, GraphiQL	grpcurl, BloomRPC	SoapUI
Best for	Public APIs, varied consumers	Tightly coupled clients, many fields	Service-to-service, perf-sensitive	Enterprise legacy, strict contracts

For most public APIs in 2025, REST + OpenAPI is the default choice. GraphQL when over-fetching is a real cost. gRPC for internal microservices.

REST design principles

1. Resources, not actions. URLs are nouns: /orders/123/refund. The verb is the HTTP method (POST a refund). Avoid /createOrder, /refundOrder — those are RPC, not REST.
2. Plural nouns for collections. /users for the collection, /users/42 for an individual. Avoid singular vs plural inconsistency (/user for one, /users for many).
3. Status codes communicate outcomes. 200 for success, 201 for created (with Location header), 204 for "succeeded, no body," 400 for bad input, 404 for missing resource. Don't return 200 with an error body — that breaks every middleware and observability tool.
4. Idempotency for retry safety. GET, PUT, DELETE should be idempotent. POST shouldn't be — but use Idempotency-Key headers to make it so when the operation matters (payments).
5. Filter, sort, paginate via query params. /users?role=admin&sort=-created_at&limit=50. Don't put filter logic in the path.
6. Versioning from day 1. Even if you only have v1, having /v1/ in the path makes it clear there could be a v2 later. Adding /v2/ next to /users later breaks every existing client.
7. Hypermedia is optional. HATEOAS purists insist; the rest of the industry doesn't bother. OpenAPI specs serve the same documentation purpose.

JavaScript: building a REST client

class UserAPI {
  constructor(baseURL, token) {
    this.baseURL = baseURL;
    this.token = token;
  }

  async _fetch(path, options = {}) {
    const r = await fetch(`${this.baseURL}${path}`, {
      ...options,
      headers: {
        'Authorization': `Bearer ${this.token}`,
        'Content-Type': 'application/json',
        ...options.headers,
      },
    });
    if (!r.ok) {
      const body = await r.text();
      throw new Error(`HTTP ${r.status}: ${body}`);
    }
    return r.status === 204 ? null : r.json();
  }

  list(params = {}) {
    const q = new URLSearchParams(params).toString();
    return this._fetch(`/users${q ? '?' + q : ''}`);
  }
  get(id)            { return this._fetch(`/users/${id}`); }
  create(data)       { return this._fetch('/users', { method: 'POST', body: JSON.stringify(data) }); }
  replace(id, data)  { return this._fetch(`/users/${id}`, { method: 'PUT', body: JSON.stringify(data) }); }
  patch(id, changes) { return this._fetch(`/users/${id}`, { method: 'PATCH', body: JSON.stringify(changes) }); }
  delete(id)         { return this._fetch(`/users/${id}`, { method: 'DELETE' }); }
}

const api = new UserAPI('https://api.example.com/v1', token);
const user = await api.get(42);
const updated = await api.patch(42, { email: '[email protected]' });

Python: building a REST server with FastAPI

from fastapi import FastAPI, HTTPException, status
from pydantic import BaseModel
from typing import Optional

app = FastAPI()

class User(BaseModel):
    id: int
    name: str
    email: str

class UserCreate(BaseModel):
    name: str
    email: str

users_db = {}  # in-memory for example

@app.get('/v1/users', response_model=list[User])
def list_users(limit: int = 50, offset: int = 0):
    return list(users_db.values())[offset:offset + limit]

@app.get('/v1/users/{user_id}', response_model=User)
def get_user(user_id: int):
    if user_id not in users_db:
        raise HTTPException(status_code=404, detail='User not found')
    return users_db[user_id]

@app.post('/v1/users', response_model=User, status_code=status.HTTP_201_CREATED)
def create_user(user: UserCreate):
    new_id = max(users_db.keys(), default=0) + 1
    users_db[new_id] = User(id=new_id, **user.model_dump())
    return users_db[new_id]

@app.delete('/v1/users/{user_id}', status_code=status.HTTP_204_NO_CONTENT)
def delete_user(user_id: int):
    if user_id not in users_db:
        raise HTTPException(status_code=404, detail='User not found')
    del users_db[user_id]

FastAPI auto-generates OpenAPI docs at /docs from your type hints. Type validation, serialization, and HTTP plumbing are handled automatically.

Pagination patterns

Style	Request	Pros	Cons
Page + per_page	?page=2&per_page=50	Intuitive, easy to jump pages	Drifts when items added/removed
Offset + limit	?offset=100&limit=50	Same as page, just different params	Same drift problem; SQL OFFSET is slow at scale
Cursor-based	?cursor=abc123&limit=50	No drift, fast at scale	Can't jump to arbitrary pages
Time-based	?since=2025-01-01T00:00:00Z	Natural for chronological feeds	Ties API shape to specific data model

For large collections (millions of rows) cursor-based pagination is the standard. Stripe, GitHub, Twitter all use it. The cursor encodes the last-seen item; the server can resume from that point in O(log n) with an indexed query.

Common REST API pitfalls

• Returning 200 with an error in the body. Breaks observability — monitoring tools count this as success. Use the right status code: 4xx for client errors, 5xx for server errors. The body explains what happened.
• Inconsistent error formats. Some endpoints return {"error": "..."}, others {"message": "..."}, others raw strings. Pick a schema and apply it everywhere. RFC 7807 (Problem Details for HTTP APIs) is a good standard.
• Missing pagination on list endpoints. Returning all 100,000 users in one response brings down clients and your own database. Always paginate; default to a sensible page size (50-100).
• Versioning by mutation. Changing the response shape of /users/42 breaks every existing client. Either don't break the contract within a version, or release v2.
• POST for everything. Using POST when GET would do the job (for queries) breaks caching and middleware tools. Use the right verb.
• Mixing query params and body for the same logical operation. Pick one. POST creates with body data; GET filters with query params. Don't accept both for one endpoint.
• No rate limiting. A buggy or malicious client can exhaust your server. Apply per-token, per-IP rate limits with 429 Too Many Requests and Retry-After header.