1st Principles
Menu

Web · 30 min read

REST APIs

Resources and representations over HTTP: designing networked interfaces around nouns, uniform methods, and evolvable contracts rather than ad-hoc RPC soup.

Why this exists

Programs need to talk to programs across trust and organizational boundaries. Without shared conventions, every integration invents a private RPC dialect that caches cannot understand and clients cannot guess.

REST is an architectural style that uses resources, representations, and uniform interfaces (often HTTP methods and status codes) to make networked APIs navigable and evolvable.

Not every JSON URL is REST. The value is in constraints that buy caching, decoupling, and clarity, not in the buzzword.

Axioms & primitives

  1. 01A resource is a conceptual target identified by a URL (URI).
  2. 02Clients manipulate representations (JSON, HTML, etc.), not the server's internal objects directly.
  3. 03Uniform interface: use shared methods and status semantics instead of inventing a new verb per action when HTTP already has one.
  4. 04Stateless request messages improve scalability; sessions are a deliberate exception layered on.
  5. 05Hypermedia (links) can advertise next valid actions; many practical APIs are REST-ish without full HATEOAS.
  6. 06Idempotence and safety of methods shape retry behavior.

Learning objectives

After this lesson you should be able to:

  • Design resource URLs and choose HTTP methods for create/read/update/delete-style operations.
  • Explain why GET caching differs from POST in intermediaries.
  • Justify why POST /getUser is a design smell using REST first principles.
  • Choose status codes for not found, validation error, and conflict at a conceptual level.
  • Describe one evolution strategy (versioning or additive changes) and its tradeoff.

Progressive depth

Read the layers in order for a full explanation. Or open the layer you need.

01

Intuition

Instead of inventing getUser and updateUser RPC names, you expose /users/42 as a resource. GET retrieves a representation. PUT/PATCH modify. DELETE removes. The shared HTTP vocabulary carries meaning for clients and intermediaries.

That uniformity is why a CDN can cache a GET of a public resource without understanding your business logic.

When teams POST everything to /api with an action field, they throw away that shared vocabulary and rebuild proprietary RPC on HTTP as dumb pipe.

02

Formal shape

Identify resources and their URIs. Choose representations and media types. Use status codes honestly. Document error bodies.

Pagination, filtering, and sorting are still resource-oriented when modeled as query parameters on collections.

Authentication may use cookies (browser first-party) or bearer tokens (Authorization header). Authorization decisions remain server-side.

Partial failure and retries: prefer idempotent designs for network uncertainty. Idempotency keys help unsafe methods.

03

Worked examples

Order API: POST /orders creates; GET /orders/123 reads; POST /orders/123/cancel may be better than overloading DELETE if cancel is a domain action with audit needs.

Public blog posts: GET /posts/slug with Cache-Control for CDNs. Drafts: authenticated, private, no shared caches.

Smell: POST /api {action:"getUser", id:42}. Better: GET /users/42 with 404 if missing.

Conflict: two clients PATCH the same resource; 412/409 with ETags makes optimistic concurrency explicit.

04

Edge cases

GraphQL and RPC can be the right tool for chatty flexible clients; do not cargo-cult REST.

True hypermedia maturity is rare; many successful APIs are resourceful HTTP without full HATEOAS.

Bulk endpoints and long-running jobs need task resources rather than multi-minute synchronous HTTP holds.

CORS is a browser rule for JS clients, not an HTTP semantic. Native mobile clients do not use CORS the same way.

Mental models

  • Library of nouns

    URLs name things (books, users, orders). Methods say what to do with the representation of the thing.

  • Document exchange

    You send and receive documents that represent state. You do not remote-control private memory graphs.

  • Contract with strangers

    Your API is a public language. Ambiguity becomes outages in someone else's midnight page.

Common misconceptions

  • Myth

    REST means JSON over HTTP.

    Reality

    JSON is a common representation. REST is about resources, uniform interface, and constraints. HTML can be RESTful too.

  • Myth

    Any CRUD URL mapping is automatically good API design.

    Reality

    You still need consistency, authz, pagination, error shape, and evolution rules.

  • Myth

    RPC is always wrong.

    Reality

    RPC styles (including gRPC) fit some internal cases. REST's strengths shine at internet-scale HTTP ecosystems and cacheable reads.

  • Myth

    Versioning in the URL is mandatory.

    Reality

    It is one strategy. Additive, backward-compatible changes can avoid breaking versions; both have costs.

Exercises

Work these without looking up answers first. Check yourself against the intent notes.

  1. Exercise 01

    Redesign POST /getOrders and POST /deleteOrder into resource-oriented endpoints. Note method and status choices.

    What good looks like

    GET /orders; DELETE /orders/{id} or POST cancel subresource; 200/204/404 as appropriate.

  2. Exercise 02

    Why can a CDN cache GET /public/cats.jpg more safely than POST /public/cats.jpg even if both returned the image bytes once?

    What good looks like

    GET safety/idempotence and caching semantics; POST is non-cacheable by default and may have side effects.

  3. Exercise 03

    Your mobile client retries a create-payment POST after a timeout. What API design reduces double charges?

    What good looks like

    Idempotency keys; or PUT with known ID; return same result on replay.

Sources & further reading

External references. Prefer primary documents and clear explainers.

Go deeper on your own

These picks go past the foundation in this lesson. Use them when you want a primary spec, official docs, or a longer walkthrough.