REST & Resource Modeling
You'll learn to
- -Model resources as nouns and operations as HTTP verbs
Every component this course has covered so far (servers, caches, queues, databases) eventually needs a contract that lets clients (and other services) actually talk to it. That contract is the API, and REST is still the dominant shape it takes.
How to design APIs that are intuitive, versioned, consistent, and safe to evolve over time.
An API is like the menu at a restaurant. The menu is the contract: it lists what's available, what information you need to provide (ingredients excluded, allergies), and what you'll get back. A good menu is clear and consistent. A bad menu changes without notice, uses different naming conventions per page, and removes dishes you rely on.
REST (Representational State Transfer): The dominant style for public APIs. Resources are nouns (users, orders, products). Operations are HTTP verbs: GET (read), POST (create), PUT/PATCH (update), DELETE (remove). Stateless - each request contains all needed information. Use status codes correctly: 200 OK, 201 Created, 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 429 Too Many Requests, 500 Server Error.
GraphQL: Clients specify exactly which fields they need in a single query. Solves over-fetching (REST endpoint returns 30 fields, you need 3) and under-fetching (needing multiple REST calls for related data). Used by GitHub API v4, Shopify, Airbnb. Trade-off: complex caching, potential N+1 query problems server-side.
gRPC: Google's RPC framework using Protocol Buffers (binary serialization). 5-7x faster than JSON. Strong typing via .proto files. Excellent for internal microservice communication where performance matters. Not browser-friendly without grpc-web.
API Versioning: Never break existing clients. Common strategies: URL path versioning (/api/v1/users), header versioning (API-Version: 2), query parameter versioning (?version=2). Maintain old versions for at least 6-12 months after deprecation.
Pagination: Never return unbounded lists. Cursor-based pagination (next_cursor token) is superior to offset pagination (page=1&size=10) for large datasets - cursor is stable when items are inserted/deleted mid-pagination.
- -Idempotency tokens: POST /payments with Idempotency-Key header prevents double charges on retry.
- -HATEOAS (optional): responses include links to related actions (rarely used in practice).
- -Always validate input server-side - never trust clients.
- -Use consistent error response shapes: { error: { code, message, details } }.
- -Document with OpenAPI/Swagger - makes client generation and testing trivial.
Should "delete a user's account" be a GET request, since it's simple to trigger from a link?
"If it's easier to test by clicking a link, that's a reasonable shortcut."
"No: GET is defined as a safe, idempotent, side-effect-free method, and tooling (browsers, crawlers, link previews) relies on that contract, prefetching GET URLs without asking. A GET that deletes data can get triggered accidentally by a crawler or a browser prefetch. Destructive or state-changing actions belong on POST/PUT/DELETE specifically because those methods promise the caller they carry side effects."