Sign in Get started

Free course · 20 lessons · Intermediate

REST APIs in Depth

Industry-standard REST API design for any stack: resource modeling, HTTP semantics, status codes, JSON conventions, pagination, filtering, bulk operations, Problem Details errors, ETags, caching, long-running operations, files and style guides.

Start the course

1. REST Foundations

What REST really means, how to model resources, and how to use HTTP methods, status codes and headers precisely.

  1. What REST Is (and Isn't) — REST constraints, the Richardson maturity model, and what 'RESTful' means in industry practice.
  2. Modeling Resources and URLs — Design nouns, collections, sub-resources and identifiers that survive change.
  3. HTTP Methods: Safe, Idempotent and Cacheable — Use GET, POST, PUT, PATCH and DELETE with their exact semantics.
  4. Status Codes That Clients Can Act On — Choose 2xx/3xx/4xx/5xx codes precisely and consistently.
  5. Headers, Content Negotiation and Representations — Media types, Accept, Content-Type, Vary, compression and custom headers.

2. Representations, Collections and Queries

Design JSON payloads, pagination, filtering, sparse fields and bulk operations.

  1. Designing JSON Representations — Naming, types, dates, money, nulls, enums and envelopes.
  2. Pagination in Depth — Offset, cursor and keyset pagination, totals, and page metadata.
  3. Filtering, Sorting and Search — Query parameter conventions, operators, allow-lists and when to use a search endpoint.
  4. Sparse Fieldsets, Expansion and Embedding — Let clients fetch less (or more) in one request without over-fetching.
  5. Bulk and Batch Operations — Create, update or delete many items efficiently with clear partial-failure semantics.

3. Correctness: Errors, Validation, Concurrency and Caching

Make APIs predictable under failure, concurrent edits and caching.

  1. Error Responses with Problem Details (RFC 9457) — One machine-readable error format for every endpoint.
  2. Validation and Field Errors — Validate at the edge and return every field error in one response.
  3. Conditional Requests, ETags and Optimistic Concurrency — Prevent lost updates and save bandwidth with validators.
  4. HTTP Caching for APIs — Cache-Control, private vs shared caches, CDNs and stale-while-revalidate for API responses.

4. Advanced Patterns and Consistency

Long-running operations, files, hypermedia and style guides.

  1. Long-Running Operations (202 + Status Resources) — Model work that takes seconds to hours without timeouts.
  2. File Uploads and Downloads — Multipart, direct-to-storage uploads, resumable transfers and range requests.
  3. Hypermedia and Links in Practice — When links in responses help, and pragmatic formats (HAL, JSON:API, RFC 8288).
  4. API Style Guides and Consistency — Codify conventions and enforce them with linting.

5. Capstone

Design and review a production REST API end to end.

  1. Capstone: Design an Orders API — Design a production-grade REST API for e-commerce orders.
  2. Capstone: Review a Flawed API — Find and fix the design problems in an existing API.