Back to roadmap
Module 5 · APIs & Application LayerDay 03925 min

REST Design Principles

Resources, verbs, and statelessness as a contract.

← PreviousNext →
Day 039

REST Design Principles

Client
client
API
service
/projects
datastore
/tasks
datastore
Signal path
Resource-oriented routing
Client
client
flow
API
service
API
service
flow
/projects
datastore
API
service
flow
/tasks
datastore
Memory hook

REST Design Principles: resources, verbs, and statelessness as a contract

Mental model

turn boundaries into contracts

Design lens

REST is great for resources, awkward for workflows.

Recall anchors
VerbsStatusConcerns

Why it matters

REST organizes APIs around resources identified by URLs and manipulated with standard HTTP verbs. Done well it's predictable, cacheable, and discoverable.

Deep dive

Nouns in URLs, verbs in HTTP. POST /orders creates; PUT /orders/123 replaces; PATCH /orders/123 modifies.

Use status codes: 200/201/204, 400/401/403/404, 409 conflict, 422 unprocessable, 429 rate-limited, 5xx for server.

Avoid /createOrder, /getThings — those reinvent verbs. Pagination, filtering, sorting via query params.

Demo / scenario

Designing a project-management API.

  1. GET /projects (list) and GET /projects/:id (one).
  2. POST /projects (create), PATCH /projects/:id (update), DELETE.
  3. Sub-resources: /projects/:id/tasks.
  4. Filtering: /projects?owner=42&status=active.

Tradeoffs

  • REST is great for resources, awkward for workflows.
  • Lots of round trips for graph-shaped data — see GraphQL day.
  • Keep operations idempotent where possible.

Diagram

Client
API
/projects
/tasks
Resource-oriented routing.

Mind map

Check yourself

Loading quiz…

Sources & further reading

← PreviousNext →