Back to library

🔌REST API Design Principles

Design REST APIs that teams can actually use — resources, verbs, versioning, and pagination, grounded in the conventions senior engineers argue about on PR threads.

Applied12 drops~2-week path · 5–8 min/daytechnology

Phase 1The Uniform Interface

Decode resources, verbs, and the uniform interface

3 drops

  1. URLs name things, not actions

    6 min

    REST models your system as a set of nouns — resources — and the HTTP verbs do the verbs.

  2. Each verb has a contract you inherit

    6 min

    HTTP methods carry semantic guarantees — safety and idempotency — that clients and infrastructure rely on.

  3. Status codes are your error language

    7 min

    HTTP status codes are a shared vocabulary — clients, monitors, and caches all speak it, so use it precisely.

Phase 2Designing Endpoints For A Real Domain

Design endpoints for a small domain end-to-end

3 drops

  1. Plural nouns, nested paths, flat filters

    7 min

    Collections are plural, individual resources nest under them, and filters live in query strings — not in the path.

  2. Shape bodies around resources, not operations

    6 min

    Request and response bodies should look like the resource itself — so that GET and PUT can round-trip the same shape.

  3. Errors are resources too

    6 min

    A well-designed error response is structured data a client can act on — not a string.

Phase 3REST In Context: RPC, GraphQL, And Tradeoffs

Weigh REST against RPC and GraphQL tradeoffs

3 drops

  1. Your teammate proposes POST /recalculateInvoice

    7 min

    RPC-style endpoints aren't evil — they're the right call when the operation isn't really a resource mutation.

  2. Your mobile team wants GraphQL

    8 min

    GraphQL solves over-fetching and under-fetching for clients; REST solves cache and infrastructure leverage. Pick based on who pays which cost.

  3. Nobody uses HATEOAS — here's why

    7 min

    HATEOAS is REST's original vision for discoverability, but in practice, clients hardcode URLs and read docs — so its real value shows up in narrow, high-leverage places.

Phase 4Ship A Versioned, Paginated API Design

Ship a versioned, paginated API design doc

3 drops

  1. Decide your versioning scheme

    8 min

    Decide your versioning scheme

  2. Design the list endpoint

    9 min

    Design the list endpoint

  3. Write the API design doc

    12 min

    Write the API design doc

Frequently asked questions

What's the difference between PUT and PATCH in REST?
This is covered in the “REST API Design Principles” learning path. Start with daily 5-minute micro-lessons that build from fundamentals to hands-on application.
How do you version a REST API without breaking clients?
This is covered in the “REST API Design Principles” learning path. Start with daily 5-minute micro-lessons that build from fundamentals to hands-on application.
Is REST still relevant when GraphQL exists?
This is covered in the “REST API Design Principles” learning path. Start with daily 5-minute micro-lessons that build from fundamentals to hands-on application.
What does 'HATEOAS' mean and does anyone actually use it?
This is covered in the “REST API Design Principles” learning path. Start with daily 5-minute micro-lessons that build from fundamentals to hands-on application.
How should I paginate a REST endpoint that returns thousands of records?
This is covered in the “REST API Design Principles” learning path. Start with daily 5-minute micro-lessons that build from fundamentals to hands-on application.

Related paths

🐍Python Decorators Introduction

Build one mental model for Python decorators that covers closures, argument passing, functools.wraps, and stacking — then ship a working caching or logging decorator from scratch in under 30 lines.

Applied~2-week path · 5-8 min/day

🦀Rust Lifetimes Explained

Stop reading `'a` as line noise and start reading it as scope arithmetic — one failing snippet at a time — until you can thread lifetimes through a small parser or iterator adapter without fighting the borrow checker.

Applied~2-week path · 5-8 min/day

☸️Kubernetes Core Concepts

Stop drowning in 30+ resource types. Build the mental model one primitive at a time -- pods, deployments, services, ingress, config -- then deploy a real app with rolling updates and health checks.

Applied~2-week path · 5-8 min/day

📈Big O Intuition

Stop treating Big O as math you memorized for an interview — build the intuition to spot O(n²) disasters, pick the right data structure without thinking, and rewrite a slow function from O(n²) to O(n) in under five minutes.

Foundations~2-week path · 5-8 min/day