REST API Cheat Sheet

Method, resource, headers, body

POST /v1/orders HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJFUzI1NiJ9...
Content-Type: application/json
Accept: application/json
Idempotency-Key: 7d1f3c2e-5b9a-4c11-9a0e-2f6c8d4b1e90

{"customerId": "cus_42", "items": [{"sku": "LAMP-01", "qty": 1}]}

HTTP/1.1 201 Created
Location: /v1/orders/ord_8812
Content-Type: application/json

{"id": "ord_8812", "status": "pending", "total": 49.0, "createdAt": "2026-10-14T09:12:03Z"}

GET with query parameters

const res = await fetch("https://httpbingo.org/anything/orders?status=paid&page=2", {
  headers: { Accept: "application/json" },
});
const body = await res.json();
console.log(res.status, body.method, body.url.split("?")[0]);
console.log(body.args);

POST JSON with curl

curl -s https://api.example.com/v1/orders \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"customerId": "cus_42", "items": [{"sku": "LAMP-01", "qty": 1}]}'

curl --json and HTTPie

curl --json '{"customerId": "cus_42"}' https://api.example.com/v1/orders
http POST api.example.com/v1/orders customerId=cus_42 Authorization:"Bearer $TOKEN"

What makes an API RESTful, per Roy Fielding (2000)

Model nouns; let the method be the verb

GET    /orders              list orders
POST   /orders              create an order
GET    /orders/8812         read one order
PATCH  /orders/8812         change some fields
DELETE /orders/8812         remove it

Four levels of REST

Every request stands on its own

GET /v1/cart HTTP/1.1
Authorization: Bearer eyJhbGciOiJFUzI1NiJ9...

REST is not CRUD over tables

Safe, idempotent, body

Replace, merge or create

PUT /users/42
{"name": "Ana", "email": "ana@example.com", "role": "admin"}
# the whole user is replaced: a field you leave out is removed or reset

PATCH /users/42
Content-Type: application/merge-patch+json
{"role": "admin"}
# only role changes

POST /users
{"name": "Ana", "email": "ana@example.com"}
# the server picks the ID and answers 201 with Location

A safe search with a complex filter

QUERY /orders HTTP/1.1
Content-Type: application/json
Accept: application/json

{"status": ["paid", "shipped"], "total": {"gte": 100}, "createdAt": {"after": "2026-01-01"}}

Ask without downloading

HEAD /files/report.pdf HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Length: 4812044
Last-Modified: Tue, 13 Oct 2026 08:00:00 GMT

OPTIONS /orders HTTP/1.1

HTTP/1.1 204 No Content
Allow: GET, POST, OPTIONS

POST to a noun that names the action

POST /orders/8812/cancellation
POST /invoices/77/payments
POST /users/42/password-reset
POST /reports/exports

Method override for old clients

POST /orders/8812 HTTP/1.1
X-HTTP-Method-Override: DELETE

The conventions most APIs follow

Identity in the path, options in the query

GET /orders/8812                       one resource, identified by ID
GET /customers/7/orders                orders that belong to customer 7
GET /orders?customerId=7&status=paid   a filtered view of the collection
GET /orders?sort=-createdAt&limit=20   sorting and page size

IDs that do not leak or collide

Precision lost in JavaScript

const id = JSON.parse('{"id": 9007199254740993}').id;
console.log(id, Number.isSafeInteger(id));

Singletons, me and search

GET /users/me                      the authenticated user
GET /orders/8812/shipping-address  a singleton sub-resource, no ID
GET /search?q=lamp&type=product    a search across several resources
GET /health                        a status endpoint for load balancers

Long URLs and limits

A response that is easy to consume

{
  "id": "ord_8812",
  "status": "paid",
  "total": {"amount": "49.00", "currency": "EUR"},
  "itemCount": 1,
  "isGift": false,
  "createdAt": "2026-10-14T09:12:03Z",
  "shippedAt": null
}

RFC 3339 in UTC

const created = new Date(Date.UTC(2026, 9, 14, 9, 12, 3));
console.log(created.toISOString());
console.log(new Date("2026-10-14T11:12:03+02:00").toISOString());

Three different meanings

{"middleName": null}   the value is known to be empty
{}                     the field was not sent or not selected
{"tags": []}           an empty list; prefer it to null for collections

Wrap collections, not single resources

{"data": [{"id": "ord_8812"}, {"id": "ord_8813"}], "nextCursor": "eyJpZCI6ODgxM30"}

Values that read well and evolve safely

{
  "status": "partially_refunded",
  "isActive": true,
  "hasAttachments": false,
  "timeoutMs": 30000,
  "weightGrams": 1250,
  "country": "RO",
  "currency": "EUR",
  "locale": "ro-RO"
}

Field names across languages

Request and response headers

Ask for a format and a language

GET /reports/q3 HTTP/1.1
Accept: text/csv, application/json;q=0.8
Accept-Language: ro, en;q=0.7

HTTP/1.1 200 OK
Content-Type: text/csv; charset=utf-8
Content-Language: ro
Vary: Accept, Accept-Language

Let the client choose how much comes back

PATCH /orders/8812 HTTP/1.1
Prefer: return=minimal

HTTP/1.1 204 No Content
Preference-Applied: return=minimal

Name them without X-

Api-Version: 2026-10-01
Request-Id: req_7Hc2kQ

Return an ID the client can quote to support

HTTP/1.1 500 Internal Server Error
Request-Id: req_7Hc2kQf9
Content-Type: application/problem+json

{"title": "Internal Server Error", "status": 500, "instance": "/v1/orders", "requestId": "req_7Hc2kQf9"}

Identify your integration

User-Agent: acme-billing-sync/2.3.1 (+https://acme.example/contact)

Success and the common failures

The two debates that never end

The standard error body

HTTP/1.1 422 Unprocessable Content
Content-Type: application/problem+json

{
  "type": "https://api.example.com/problems/validation",
  "title": "Your request is not valid.",
  "status": 422,
  "detail": "2 fields are invalid.",
  "instance": "/v1/orders",
  "errors": [
    {"pointer": "#/items/0/qty", "detail": "must be at least 1"},
    {"pointer": "#/customerId", "detail": "unknown customer"}
  ]
}

Add a stable code for programs

{
  "type": "https://api.example.com/problems/card-declined",
  "title": "The card was declined.",
  "status": 402,
  "code": "card_declined",
  "declineCode": "insufficient_funds"
}

What every error response should do

One handler for every problem+json response

import json

def describe(status, content_type, body):
    if content_type.startswith("application/problem+json"):
        p = json.loads(body)
        lines = [f"{status} {p.get('title', 'Error')}"]
        for e in p.get("errors", []):
            lines.append(f"  {e.get('pointer', '?')}: {e.get('detail', '')}")
        return "\n".join(lines)
    return f"{status} (no problem details)"

body = '{"type": "about:blank", "title": "Your request is not valid.", "status": 422, "errors": [{"pointer": "#/qty", "detail": "must be at least 1"}]}'
print(describe(422, "application/problem+json", body))
print(describe(502, "text/html", "<html>Bad gateway</html>"))

Offset, page and cursor

GET /orders?offset=100&limit=50
GET /orders?page=3&per_page=50
GET /orders?limit=50&after=eyJpZCI6ODgxMn0

Compare them

Keyset pagination with an opaque cursor

const last = { createdAt: "2026-10-14T09:12:03Z", id: "ord_8812" };
const cursor = Buffer.from(JSON.stringify(last)).toString("base64url");
console.log(cursor);
console.log(JSON.parse(Buffer.from(cursor, "base64url").toString()));

Navigation links in a header (RFC 8288)

HTTP/1.1 200 OK
Link: <https://api.example.com/orders?page=4&per_page=50>; rel="next", <https://api.example.com/orders?page=25&per_page=50>; rel="last", <https://api.example.com/orders?page=1&per_page=50>; rel="first", <https://api.example.com/orders?page=2&per_page=50>; rel="prev"

Parse a Link header

const header = '<https://api.example.com/orders?page=4>; rel="next", <https://api.example.com/orders?page=25>; rel="last"';
const links = Object.fromEntries(
  header.split(",").map((part) => {
    const [, url, rel] = part.match(/<([^>]+)>;\s*rel="([^"]+)"/);
    return [rel, url];
  })
);
console.log(links.next);
console.log(Object.keys(links));

requests parses Link headers for you

import requests

r = requests.get(
    "https://api.github.com/repos/nodejs/node/issues",
    params={"per_page": 2, "state": "closed"},
    headers={"Accept": "application/vnd.github+json", "User-Agent": "cheat-sheet-demo"},
    timeout=10,
)
print(r.status_code, len(r.json()))
print(sorted(r.links))
print(r.links["next"]["url"])

Fetch every page in JavaScript

async function* pages(url) {
  while (url) {
    const res = await fetch(url, { headers: { Accept: "application/json" } });
    if (!res.ok) throw new Error(`HTTP ${res.status}`);
    const body = await res.json();
    yield body.data;
    url = body.next ?? null;
  }
}

for await (const batch of pages("https://api.example.com/orders?limit=100")) {
  console.log(batch.length);
}

Defaults and maximums

GET /orders                 returns the default page, for example 20 items
GET /orders?limit=100       allowed
GET /orders?limit=100000    capped at the maximum, or rejected with 400

Simple filters as plain query parameters

GET /orders?status=paid
GET /orders?status=paid,shipped
GET /orders?createdAfter=2026-01-01&totalMin=100
GET /orders?q=lamp

Bracket and operator styles

GET /orders?filter[status]=paid&filter[total][gte]=100
GET /orders?total[gte]=100&total[lt]=500

Sort, select and expand

GET /orders?sort=-createdAt,total
GET /orders?fields=id,status,total
GET /orders/8812?expand=customer,items.product

Reject what you do not support

GET /orders?statsu=paid HTTP/1.1

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json

{"title": "Unknown query parameter", "status": 400, "detail": "statsu is not a supported filter; did you mean status?"}

Conventions worth writing down

Send only what changes; null removes a field

PATCH /users/42 HTTP/1.1
Content-Type: application/merge-patch+json

{"email": "ana@new.example", "nickname": null, "address": {"city": "Cluj"}}

The algorithm, in eight lines

function mergePatch(target, patch) {
  if (patch === null || typeof patch !== "object" || Array.isArray(patch)) return patch;
  const out = target && typeof target === "object" && !Array.isArray(target) ? { ...target } : {};
  for (const [k, v] of Object.entries(patch)) {
    if (v === null) delete out[k];
    else out[k] = mergePatch(out[k], v);
  }
  return out;
}

const user = { email: "ana@example.com", nickname: "ana", address: { city: "Iasi", zip: "700000" }, tags: ["a", "b"] };
console.log(JSON.stringify(mergePatch(user, { email: "ana@new.example", nickname: null, address: { city: "Cluj" }, tags: ["c"] })));

Explicit operations, including array edits

PATCH /users/42 HTTP/1.1
Content-Type: application/json-patch+json

[
  {"op": "test", "path": "/version", "value": 7},
  {"op": "replace", "path": "/email", "value": "ana@new.example"},
  {"op": "add", "path": "/tags/-", "value": "vip"},
  {"op": "remove", "path": "/nickname"}
]

Combine PATCH with If-Match

PATCH /orders/8812 HTTP/1.1
Content-Type: application/merge-patch+json
If-Match: "v41"

{"shippingAddress": {"city": "Cluj"}}

Which format to accept

One request, a result per item

POST /v1/products/bulk HTTP/1.1
Content-Type: application/json

{"items": [{"sku": "LAMP-01", "price": "49.00"}, {"sku": "LAMP-02", "price": "-1"}]}

HTTP/1.1 200 OK
Content-Type: application/json

{"results": [
  {"index": 0, "status": 201, "id": "prod_1"},
  {"index": 1, "status": 422, "error": {"pointer": "#/items/1/price", "detail": "must be positive"}}
]}

Several operations in one request

POST /v1/batch HTTP/1.1
Content-Type: application/json

{"requests": [
  {"method": "GET", "url": "/v1/orders/8812"},
  {"method": "PATCH", "url": "/v1/orders/8813", "body": {"status": "shipped"}}
]}

HAL style

{
  "id": "ord_8812",
  "status": "pending",
  "_links": {
    "self": {"href": "/orders/8812"},
    "customer": {"href": "/customers/42"},
    "cancel": {"href": "/orders/8812/cancellation", "method": "POST"}
  }
}

A complete specification for JSON APIs

{
  "data": {
    "type": "orders",
    "id": "8812",
    "attributes": {"status": "pending", "total": "49.00"},
    "relationships": {"customer": {"data": {"type": "customers", "id": "42"}}}
  },
  "included": [{"type": "customers", "id": "42", "attributes": {"name": "Ana"}}]
}

Four common strategies

GET /v1/orders                                   in the path
GET /orders  Api-Version: 2026-10-01              in a header, date based
GET /orders  Accept: application/vnd.example.v2+json   in the media type
GET /orders?api-version=2026-10-01               in the query (Azure style)

Breaking and non-breaking changes

Announce the end in headers

HTTP/1.1 200 OK
Deprecation: @1798761600
Sunset: Sat, 01 May 2027 00:00:00 GMT
Link: <https://api.example.com/docs/migrate-v2>; rel="deprecation"; type="text/html"

Tolerant reading of enums

const LABELS = { pending: "Waiting", paid: "Paid", shipped: "On its way" };

function statusLabel(status) {
  return LABELS[status] ?? "Updated";
}

What every API change log entry needs

One resource, described completely

openapi: 3.2.0
info:
  title: Orders API
  version: 1.4.0
servers:
  - url: https://api.example.com/v1
paths:
  /orders/{orderId}:
    get:
      operationId: getOrder
      summary: Get one order
      parameters:
        - name: orderId
          in: path
          required: true
          schema: { type: string }
      responses:
        "200":
          description: The order
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Order" }
        "404":
          description: No such order
          content:
            application/problem+json:
              schema: { $ref: "#/components/schemas/Problem" }
components:
  schemas:
    Order:
      type: object
      required: [id, status]
      properties:
        id: { type: string, examples: ["ord_8812"] }
        status: { type: string, enum: [pending, paid, shipped] }
        createdAt: { type: string, format: date-time }
    Problem:
      type: object
      properties:
        type: { type: string, format: uri-reference }
        title: { type: string }
        status: { type: integer }

Versions you will meet

Bearer tokens and API keys

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    apiKey:
      type: apiKey
      in: header
      name: X-Api-Key
security:
  - bearerAuth: []

Lint, mock, generate, document

npx @redocly/cli lint openapi.yaml
npx @stoplight/prism-cli mock openapi.yaml
npx @openapitools/openapi-generator-cli generate -i openapi.yaml -g typescript-fetch -o ./client
docker run -p 8080:8080 -e SWAGGER_JSON=/spec/openapi.yaml -v "$PWD":/spec swaggerapi/swagger-ui

Shared parameters and responses

components:
  parameters:
    Limit:
      name: limit
      in: query
      schema: { type: integer, minimum: 1, maximum: 100, default: 20 }
  responses:
    NotFound:
      description: Not found
      content:
        application/problem+json:
          schema: { $ref: "#/components/schemas/Problem" }
paths:
  /orders:
    get:
      parameters:
        - $ref: "#/components/parameters/Limit"
      responses:
        "200": { description: OK }
        "404": { $ref: "#/components/responses/NotFound" }

Describe what you send, not only what you receive

webhooks:
  paymentSucceeded:
    post:
      requestBody:
        content:
          application/json:
            schema: { $ref: "#/components/schemas/PaymentEvent" }
      responses:
        "204":
          description: Received

Frameworks that write OpenAPI for you

Twelve questions

Seen in most API reviews

Who is calling decides the method

Headers, never the URL

GET /v1/orders HTTP/1.1
Authorization: Bearer eyJhbGciOiJFUzI1NiIsImtpZCI6ImsxIn0...

GET /v1/orders HTTP/1.1
X-Api-Key: sk_live_a1b2c3...

A server gets a token for itself

POST /oauth/token HTTP/1.1
Host: auth.example.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=

grant_type=client_credentials&scope=orders:read

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store

{"access_token": "eyJhbGciOiJFUzI1NiJ9...", "token_type": "Bearer", "expires_in": 3600, "scope": "orders:read"}

Make the verifier and the challenge

const crypto = require("crypto");
const verifier = crypto.randomBytes(32).toString("base64url");
const challenge = crypto.createHash("sha256").update(verifier).digest("base64url");
console.log(verifier.length, challenge.length, /^[A-Za-z0-9_-]+$/.test(challenge));

What the header really contains

const header = "Basic " + Buffer.from("client_id:client_secret").toString("base64");
console.log(header);
console.log(Buffer.from(header.slice(6), "base64").toString());

Keep only a hash on the server

A client certificate instead of a secret

curl --cert client.pem --key client-key.pem https://partner-api.example.com/v1/orders

Three base64url parts, separated by dots

const token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c";
const [header, payload] = token.split(".").slice(0, 2).map((p) => JSON.parse(Buffer.from(p, "base64url").toString()));
console.log(header);
console.log(payload);

The checks a server must make

Short access tokens, rotated refresh tokens

HS256 is HMAC-SHA256 over header.payload

const crypto = require("crypto");
const token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c";
const [h, p, sig] = token.split(".");
const expected = crypto.createHmac("sha256", "your-256-bit-secret").update(`${h}.${p}`).digest("base64url");
console.log(expected === sig);

Verify with the jose library

import { createRemoteJWKSet, jwtVerify } from "jose";

const JWKS = createRemoteJWKSet(new URL("https://auth.example.com/.well-known/jwks.json"));

const { payload } = await jwtVerify(token, JWKS, {
  issuer: "https://auth.example.com/",
  audience: "https://api.example.com",
  algorithms: ["ES256", "RS256"],
});

The current list and the fix for each

The most common API vulnerability

app.get("/orders/:id", requireAuth, async (req, res) => {
  const order = await db.orders.findById(req.params.id);
  if (!order || order.customerId !== req.user.customerId) {
    return res.status(404).json({ title: "Not Found", status: 404 });
  }
  res.json(order);
});

Never bind the request body straight to the model

const ALLOWED = ["name", "email", "address"];
const changes = Object.fromEntries(Object.entries(req.body).filter(([k]) => ALLOWED.includes(k)));
await db.users.update(req.user.id, changes);

Baseline rules

Fetching a URL a client gave you

const allowed = new Set(["images.example-cdn.com", "uploads.example.com"]);

function checkUrl(input) {
  const url = new URL(input);
  if (url.protocol !== "https:" || !allowed.has(url.hostname)) {
    throw new Error("URL not allowed");
  }
  return url;
}

Slow down guessing

POST /oauth/token HTTP/1.1

HTTP/1.1 429 Too Many Requests
Retry-After: 60

A preflight, then the real request

OPTIONS /v1/orders HTTP/1.1
Origin: https://app.example.com
Access-Control-Request-Method: PATCH
Access-Control-Request-Headers: authorization, content-type

HTTP/1.1 204 No Content
Access-Control-Allow-Origin: https://app.example.com
Access-Control-Allow-Methods: GET, POST, PATCH, DELETE
Access-Control-Allow-Headers: Authorization, Content-Type
Access-Control-Allow-Credentials: true
Access-Control-Max-Age: 600
Vary: Origin

Why CORS errors happen

Which requests trigger a preflight

Send a preflight by hand

curl -s -o /dev/null -D - -X OPTIONS https://httpbingo.org/anything -H "Origin: https://app.example.com" -H "Access-Control-Request-Method: PATCH" -H "Access-Control-Request-Headers: authorization" | grep -i "^access-control"

Pick one per endpoint

Prevent lost updates with ETag and If-Match

GET /docs/7 HTTP/1.1

HTTP/1.1 200 OK
ETag: "v41"

PUT /docs/7 HTTP/1.1
If-Match: "v41"
Content-Type: application/json

{"title": "New title", "body": "..."}

HTTP/1.1 412 Precondition Failed

A strong ETag from the body

const crypto = require("crypto");
const body = JSON.stringify({ id: "ord_8812", status: "paid" });
const etag = '"' + crypto.createHash("sha256").update(body).digest("base64url").slice(0, 16) + '"';
console.log(etag);

Revalidate instead of downloading again

let cached = null;

async function getConfig() {
  const res = await fetch("/api/config", {
    headers: cached ? { "If-None-Match": cached.etag } : {},
  });
  if (res.status === 304) return cached.data;
  cached = { etag: res.headers.get("etag"), data: await res.json() };
  return cached.data;
}

Make POST safe to retry

POST /v1/payments HTTP/1.1
Idempotency-Key: 5c1d2a5e-3f0b-4d7e-9c8a-6b2f1e0d4c3b
Content-Type: application/json

{"amount": "49.00", "currency": "EUR", "source": "card_123"}

Server side, in short

const cached = await store.get(key);
if (cached) return res.status(cached.status).json(cached.body);
const result = await createPayment(req.body);
await store.set(key, { status: 201, body: result }, { ttlSeconds: 86400 });
res.status(201).json(result);

What a client may retry

One key per logical operation

const key = crypto.randomUUID();
console.log(key.length, /^[0-9a-f-]{36}$/.test(key), key.charAt(14));

Four common ways to count

Tell the client how long to wait

HTTP/1.1 429 Too Many Requests
Retry-After: 21
RateLimit-Policy: "default";q=100;w=60
RateLimit: "default";r=0;t=21
Content-Type: application/problem+json

{"title": "Too many requests", "status": 429, "detail": "100 requests per minute allowed"}

Bursts allowed, average rate enforced

function bucket(capacity, refillPerSec) {
  let tokens = capacity, last = 0;
  return (nowMs) => {
    tokens = Math.min(capacity, tokens + ((nowMs - last) / 1000) * refillPerSec);
    last = nowMs;
    if (tokens < 1) return false;
    tokens -= 1;
    return true;
  };
}

const allow = bucket(5, 1);
const burst = [0, 10, 20, 30, 40, 50, 60].map((t) => allow(t));
console.log(burst.join(" "));
console.log(allow(2000), allow(2010), allow(2020));

Retry with urllib3 and requests

import requests
from requests.adapters import HTTPAdapter
from urllib3.util import Retry

retry = Retry(total=5, backoff_factor=0.5, status_forcelist=[429, 500, 502, 503, 504])
session = requests.Session()
session.mount("https://", HTTPAdapter(max_retries=retry))
r = session.get("https://api.example.com/v1/orders", timeout=10)

Accept, then let the client poll

POST /v1/exports HTTP/1.1

HTTP/1.1 202 Accepted
Location: /v1/exports/exp_31

GET /v1/exports/exp_31 HTTP/1.1

HTTP/1.1 200 OK
{"id": "exp_31", "status": "running", "progress": 0.6}

GET /v1/exports/exp_31 HTTP/1.1

HTTP/1.1 200 OK
{"id": "exp_31", "status": "done", "download": "https://files.example.com/exp_31.csv?sig=..."}

A delivery from the provider

POST /webhooks/payments HTTP/1.1
Content-Type: application/json
X-Signature: sha256=1f0e3a9c...
X-Timestamp: 1792056723

{"id": "evt_901", "type": "payment.succeeded", "data": {"paymentId": "pay_77"}}

Verify the HMAC signature

const crypto = require("crypto");
const secret = "whsec_test_123";
const body = '{"id":"evt_901","type":"payment.succeeded"}';
const timestamp = "1792056723";
const sent = "sha256=" + crypto.createHmac("sha256", secret).update(`${timestamp}.${body}`).digest("hex");

function verify(rawBody, header, ts) {
  const expected = "sha256=" + crypto.createHmac("sha256", secret).update(`${ts}.${rawBody}`).digest("hex");
  return header.length === expected.length && crypto.timingSafeEqual(Buffer.from(header), Buffer.from(expected));
}
console.log(verify(body, sent, timestamp));
console.log(verify(body.replace("succeeded", "failed"), sent, timestamp));

Stream updates instead of polling

GET /v1/exports/exp_31/events HTTP/1.1
Accept: text/event-stream

HTTP/1.1 200 OK
Content-Type: text/event-stream

event: progress
data: {"progress": 0.6}

event: done
data: {"download": "https://files.example.com/exp_31.csv"}

What providers and receivers agree on

multipart/form-data

curl -F "file=@invoice.pdf;type=application/pdf" -F "orderId=ord_8812" https://api.example.com/v1/documents

Presigned URLs for large files

POST /v1/uploads HTTP/1.1
Content-Type: application/json

{"filename": "video.mp4", "size": 734003200, "contentType": "video/mp4"}

HTTP/1.1 201 Created
Content-Type: application/json

{"uploadUrl": "https://bucket.s3.amazonaws.com/u/91?X-Amz-Signature=...", "expiresIn": 900, "fileId": "file_91"}

Name the file and support ranges

HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename="invoice-8812.pdf"
Content-Length: 48211
Accept-Ranges: bytes

FormData with fetch

const form = new FormData();
form.append("file", input.files[0]);
form.append("orderId", "ord_8812");

const res = await fetch("/v1/documents", { method: "POST", body: form });

Large files over unreliable networks

fetch, in browsers and Node.js 18+

const res = await fetch("https://httpbingo.org/post", {
  method: "POST",
  headers: { "Content-Type": "application/json", Accept: "application/json" },
  body: JSON.stringify({ customerId: "cus_42", qty: 1 }),
  signal: AbortSignal.timeout(10000),
});
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const echo = await res.json();
console.log(res.status, echo.json);

requests

import requests

r = requests.post(
    "https://httpbingo.org/post",
    json={"customerId": "cus_42", "qty": 1},
    timeout=10,
)
r.raise_for_status()
print(r.status_code, r.json()["json"])

java.net.http.HttpClient, Java 11+

HttpClient client = HttpClient.newBuilder()
    .connectTimeout(Duration.ofSeconds(5))
    .build();
HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.example.com/v1/orders"))
    .timeout(Duration.ofSeconds(10))
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString("{\"customerId\":\"cus_42\",\"qty\":1}"))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.statusCode() + " " + response.body());

net/http

body := strings.NewReader(`{"customerId":"cus_42","qty":1}`)
client := &http.Client{Timeout: 10 * time.Second}
resp, err := client.Post("https://api.example.com/v1/orders", "application/json", body)
if err != nil {
	return err
}
defer resp.Body.Close()
if resp.StatusCode >= 300 {
	return fmt.Errorf("unexpected status %d", resp.StatusCode)
}

HttpClient and System.Net.Http.Json

using var http = new HttpClient { Timeout = TimeSpan.FromSeconds(10) };
var response = await http.PostAsJsonAsync("https://api.example.com/v1/orders", new { customerId = "cus_42", qty = 1 });
response.EnsureSuccessStatusCode();
var order = await response.Content.ReadFromJsonAsync<Order>();

Invoke-RestMethod

$body = @{ customerId = "cus_42"; qty = 1 } | ConvertTo-Json
Invoke-RestMethod -Method Post -Uri "https://api.example.com/v1/orders" `
  -ContentType "application/json" -Body $body `
  -Headers @{ Authorization = "Bearer $env:TOKEN" }

Defaults that bite

Express 5

const express = require("express");
const app = express();
app.use(express.json());

app.get("/orders", async (req, res) => res.json({ data: await db.orders.list(req.query) }));
app.get("/orders/:id", async (req, res) => {
  const order = await db.orders.get(req.params.id);
  if (!order) return res.status(404).json({ title: "Not Found", status: 404 });
  res.json(order);
});
app.post("/orders", async (req, res) => {
  const order = await db.orders.create(req.body);
  res.status(201).location(`/orders/${order.id}`).json(order);
});
app.delete("/orders/:id", async (req, res) => { await db.orders.remove(req.params.id); res.sendStatus(204); });
app.listen(3000);

FastAPI

from fastapi import FastAPI, HTTPException, Response, status
from pydantic import BaseModel

app = FastAPI()

class OrderIn(BaseModel):
    customer_id: str
    qty: int = 1

@app.get("/orders/{order_id}")
def get_order(order_id: str):
    order = db.get(order_id)
    if order is None:
        raise HTTPException(status_code=404, detail="Order not found")
    return order

@app.post("/orders", status_code=status.HTTP_201_CREATED)
def create_order(order: OrderIn, response: Response):
    saved = db.create(order)
    response.headers["Location"] = f"/orders/{saved.id}"
    return saved

Spring Boot

@RestController
@RequestMapping("/orders")
class OrderController {
    private final OrderRepository repository;
    OrderController(OrderRepository repository) { this.repository = repository; }

    @GetMapping("/{id}")
    Order get(@PathVariable String id) {
        return repository.findById(id)
            .orElseThrow(() -> new ResponseStatusException(HttpStatus.NOT_FOUND));
    }

    @PostMapping
    ResponseEntity<Order> create(@Valid @RequestBody OrderRequest body) {
        Order saved = repository.save(body.toOrder());
        return ResponseEntity.created(URI.create("/orders/" + saved.id())).body(saved);
    }

    @DeleteMapping("/{id}")
    @ResponseStatus(HttpStatus.NO_CONTENT)
    void delete(@PathVariable String id) { repository.deleteById(id); }
}

ASP.NET Core minimal API

var orders = app.MapGroup("/orders");
orders.MapGet("/{id}", async (string id, AppDb db) =>
    await db.Orders.FindAsync(id) is { } order ? Results.Ok(order) : Results.NotFound());
orders.MapPost("/", async (OrderIn input, AppDb db) =>
{
    var order = db.Orders.Add(input.ToOrder()).Entity;
    await db.SaveChangesAsync();
    return TypedResults.Created($"/orders/{order.Id}", order);
});
orders.MapDelete("/{id}", async (string id, AppDb db) =>
{
    await db.Orders.Where(o => o.Id == id).ExecuteDeleteAsync();
    return Results.NoContent();
});

Go 1.22+ net/http

mux := http.NewServeMux()
mux.HandleFunc("GET /orders/{id}", func(w http.ResponseWriter, r *http.Request) {
	order, ok := store.Get(r.PathValue("id"))
	if !ok {
		http.Error(w, "not found", http.StatusNotFound)
		return
	}
	w.Header().Set("Content-Type", "application/json")
	json.NewEncoder(w).Encode(order)
})
mux.HandleFunc("DELETE /orders/{id}", func(w http.ResponseWriter, r *http.Request) {
	store.Delete(r.PathValue("id"))
	w.WriteHeader(http.StatusNoContent)
})
http.ListenAndServe(":8080", mux)

Laravel

Route::apiResource('orders', OrderController::class);

class OrderController extends Controller
{
    public function show(Order $order) { return $order; }

    public function store(StoreOrderRequest $request)
    {
        $order = Order::create($request->validated());
        return response()->json($order, 201)->header('Location', "/api/orders/{$order->id}");
    }

    public function destroy(Order $order) { $order->delete(); return response()->noContent(); }
}

curl -v

curl -sv -o /dev/null "https://httpbingo.org/status/204" 2>&1 | grep -E "^(> [A-Z]{3,7} |> Accept|< HTTP)"

Run a Postman collection in CI

newman run orders.postman_collection.json -e staging.postman_environment.json --reporters cli,junit

Fuzz an API against its own OpenAPI document

schemathesis run https://api.example.com/openapi.json

Pact in one paragraph

Three API styles

SOAP and RPC over HTTP