TodayTools

REST API design flashcards

Design clear, predictable HTTP APIs people enjoy using.

Donate
Beginner friendly, starts from zero
Section
How to study
0
REST API designStart from zero · 1 of 12

What is a REST API, in one plain sentence?

A set of agreed web addresses and rules that lets one program ask another program for data, or ask it to do something.

API = a menu other programs can order from.

All topics

REST API design at a glance

A REST API is a set of agreed web addresses and rules that lets one program ask another for data or to do a job.

It is like a restaurant waiter: you order from the menu, the kitchen cooks, and the waiter brings the dish, so you never enter the kitchen.

Words you will meet

Client
The program that asks, such as a phone app or a browser
Server
A computer that is always on and answers requests
Request
The message a client sends to ask for something
Response
The reply the server sends back
Resource
A thing the API lets you work with, such as an order
Method
The action word of a request, such as GET to read or POST to create
Status code
A three-digit number saying how a request went, such as 200 or 404
JSON
A simple text format of names and values inside curly braces

The steps

  1. 1. Start from zero (12 cards): What an API is, how client and server talk, and your first request read end to end.
  2. 2. Core basics (15 cards): Resources, HTTP methods, status codes, JSON and your first requests.
  3. 3. Next steps (16 cards): Filtering, pagination, errors, idempotency, auth, versioning and OpenAPI.
  4. 4. Go deeper (16 cards): Caching, concurrency, async work, webhooks, security and API evolution.
All 12 cards in Start from zero
What is a REST API, in one plain sentence?
A set of agreed web addresses and rules that lets one program ask another program for data, or ask it to do something.
What problem do APIs solve?
Without a shared way to talk, every app would need special code for every service it uses. REST gives everyone one simple pattern built on how the web already works.
Where do you already meet APIs in daily life?
When a weather app shows today's rain, a food app tracks your delivery, or a payment goes through, the app is calling APIs behind the screen.
What is an everyday picture of an API?
A restaurant waiter. You read the menu, tell the waiter your order, the kitchen cooks, and the waiter brings the dish. You never walk into the kitchen yourself.
What are a client, a server, a request, a response and HTTP?
The client (your app or browser) sends a request. The server, a computer that is always on, sends back a response. HTTP is the shared web language they both use.
What are a URL, a path and a query string?
A URL is a web address. The path is the part after the site name that says which thing, like /orders/7. The query string after ? adds options, like ?status=paid.
What are a resource and a method?
A resource is a thing the API lets you work with, like an order or a user. The method is the action word: GET reads, POST creates, PATCH changes part, PUT replaces, DELETE removes.
What is a status code?
A three-digit number in every response that says how it went: 200 means OK, 404 means not found, and 500 means the server broke.
What are headers, the body and JSON?
Headers are short labels on a message, like the address on an envelope. The body is the letter inside, usually written in JSON: names and values inside curly braces.
Your first tiny win: read this request and its response.
The client sends a GET for the weather resource, with a query string naming the city. The server replies 200 OK and a JSON body saying it is 31 degrees.
What do you need before starting this topic?
Just a browser to begin. Later cards use curl, a small tool already on most Mac, Linux and Windows computers, typed into a terminal (a text window for commands).
What will you be able to do after this topic?
Design clean URLs, choose the right method and status code, send and read requests with curl, and spot common API design mistakes in a review.
REST API design cheatsheet

Methods

  • GET /orders?status=paid List, safe, cacheable
  • GET /orders/{id} Read one
  • POST /orders Create; 201 + Location
  • PUT /orders/{id} Replace whole, idempotent
  • PATCH /orders/{id} Partial update
  • DELETE /orders/{id} Remove; 204, idempotent
  • POST /orders/{id}/refunds Action as a sub-resource

Status codes

  • 200 / 201 / 202 / 204 OK, Created, Accepted, No Content
  • 304 Not Modified (ETag matched)
  • 400 / 422 Malformed / invalid data
  • 401 / 403 Who are you / not allowed
  • 404 / 409 Not found / state conflict
  • 412 If-Match failed (lost update stopped)
  • 429 Too many requests + Retry-After
  • 502 / 503 / 504 Upstream issues, safe to retry

Request headers

  • Authorization: Bearer <token> Credentials
  • Content-Type / Accept Body format / wanted format
  • Idempotency-Key: <uuid> Safe POST retries
  • If-None-Match: "etag" Conditional GET
  • If-Match: "etag" Optimistic concurrency
  • traceparent Distributed trace id

Response headers

  • Location: /orders/9002 Where the new thing lives
  • ETag: "v17" Version of this representation
  • Cache-Control: private, max-age=60 Cache rules
  • Retry-After: 30 When to try again
  • Deprecation / Sunset Retirement notice
  • Content-Type: application/problem+json RFC 9457 error
  • Vary: Origin, Accept-Encoding Cache per header

Query patterns

  • ?status=paid&city=Pune Field filters
  • ?createdFrom=...&createdTo=... Half-open ranges
  • ?sort=-createdAt,id Sort, - for descending
  • ?limit=50&cursor=... Cursor pagination
  • ?fields=id,name Sparse fieldsets
  • ?expand=customer Embed related object
  • ?q=tea Free-text search
Donate