DEV Community: Mean

HTTP Caching for APIs: Cache-Control, max-age, and stale-while-revalidate

Mean — Sun, 28 Jun 2026 05:56:22 +0000

Most API teams reach for a Redis cache or a CDN long before they've spent the one HTTP header that does the job for free. Cache-Control lets clients, proxies, and CDNs cache your responses correctly without you running any infrastructure. Get it right and a huge slice of your traffic never touches your origin. Get it wrong and you either serve stale data or melt your database. Here's how to think about it.

The header that does the work

Cache-Control is a response header that tells every cache in the chain how long a response stays fresh and who is allowed to store it.

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: public, max-age=300

{"id": 42, "name": "Widget", "price": 1999}

max-age=300 means the response is fresh for 300 seconds. During that window, a browser or CDN serves its stored copy without asking your server at all. public means shared caches (CDNs, proxies) may store it; use private for per-user data so a CDN never serves one user's response to another.

For data that must never be cached:

Cache-Control: no-store

And for data you can cache but must revalidate every time before using:

Cache-Control: no-cache, max-age=0

no-cache is the most misunderstood directive — it does not mean "don't cache." It means "store it, but check with the origin before serving." That check is cheap when you pair it with an ETag.

Setting it from your code

In Express, set freshness per route based on how volatile the data is:

app.get("/products/:id", async (req, res) => {
  const product = await db.products.find(req.params.id);

  // Product catalog changes rarely — cache for 5 min in shared caches
  res.set("Cache-Control", "public, max-age=300");
  res.json(product);
});

app.get("/me", async (req, res) => {
  const user = await getUser(req);

  // Personal data — only the user's own browser may cache it
  res.set("Cache-Control", "private, max-age=30");
  res.json(user);
});

The rule of thumb: pick a max-age you'd be comfortable serving stale for. A currency rate that updates hourly can use max-age=3600. A live inventory count probably wants max-age=10 or no-cache.

The directive that changes everything: stale-while-revalidate

The hard part of caching is the moment a cached entry expires. Naively, the next request blocks while you regenerate the response — so every cache expiry produces one slow request, and under load a "cache stampede" can hit your origin with thousands of simultaneous regenerations.

stale-while-revalidate fixes this:

Cache-Control: public, max-age=60, stale-while-revalidate=300

This says: serve from cache for 60 seconds. After that, for up to 300 more seconds, keep serving the stale copy instantly while refreshing it in the background. The user never waits. Your origin gets exactly one revalidation request instead of a thundering herd.

You can test the behavior with a quick fetch loop:

async function poll(url, times = 5) {
  for (let i = 0; i < times; i++) {
    const res = await fetch(url);
    console.log(res.status, res.headers.get("age"), res.headers.get("x-cache"));
    await new Promise(r => setTimeout(r, 1000));
  }
}

poll("https://api.example.com/products/42");

Watch the age header climb while the response is served from cache, then reset after a background revalidation — all without a single slow request on the client side.

A safe default to copy

If you only remember one line, make read-only, non-personalized endpoints return:

Cache-Control: public, max-age=60, stale-while-revalidate=600

Short freshness so data isn't badly out of date, a long SWR window so a cold cache never causes a latency spike, and public so your CDN absorbs the load. Pair it with an ETag and conditional requests for the cases where the data really hasn't changed and you want the cache to confirm cheaply.

Knowing what your API actually sends

The tricky part of caching is that the right header depends on the endpoint, and it's easy to ship no-store everywhere "to be safe" and quietly throw away your performance. If you want to inspect, document, and test caching headers across every endpoint in one place — and share that with your team — APIKumo lets you organize your API collections, run requests, and see exactly which Cache-Control directives each route returns, so your caching strategy is something you can verify instead of guess at.

Correlation IDs: Trace a Single Request Across Every Service in Your API

Mean — Mon, 22 Jun 2026 02:54:08 +0000

The Problem: One Request, Five Services, Zero Clues

A user reports that "saving their profile failed." You open your logs and find a 500. But that single request touched your API gateway, an auth service, a profile service, and a database proxy. Each one logged something — but nothing ties those lines together. You're left grepping by timestamp and praying no one else made a request in the same second.

A correlation ID (also called a request ID or trace ID) fixes this. It's a single unique value attached to a request when it enters your system and propagated to every downstream call and log line. One ID, one full story.

Step 1: Accept or Generate the ID at the Edge

The rule: if an incoming request already carries a correlation ID header, reuse it. If not, generate one. This lets clients and upstream services thread their own IDs through your stack.

Here's an Express middleware that does exactly that:

import { randomUUID } from "node:crypto";
import { AsyncLocalStorage } from "node:async_hooks";

export const requestContext = new AsyncLocalStorage();

export function correlationId(req, res, next) {
  const incoming = req.header("x-correlation-id");
  const id = incoming || randomUUID();

  // Echo it back so clients can log it too
  res.setHeader("x-correlation-id", id);

  // Make it available anywhere in this request, no prop-drilling
  requestContext.run({ correlationId: id }, () => next());
}

AsyncLocalStorage is the key trick: it gives you per-request storage that survives async/await without passing req into every function.

Step 2: Put the ID in Every Log Line

A correlation ID is worthless if it isn't in your logs. Wrap your logger so it reads from context automatically:

function log(level, message, meta = {}) {
  const store = requestContext.getStore();
  console.log(JSON.stringify({
    level,
    message,
    correlationId: store?.correlationId ?? "none",
    timestamp: new Date().toISOString(),
    ...meta,
  }));
}

// Anywhere in your code — no need to pass the ID around:
log("info", "profile updated", { userId: 42 });
// {"level":"info","message":"profile updated","correlationId":"a1b2...","userId":42,...}

Now a single grep (or a Loki/Datadog filter) on the ID returns every line for that request, in order.

Step 3: Propagate Downstream

The ID has to ride along on every outbound call, or the trail dies at your service boundary. Patch your HTTP client to inject it:

async function fetchWithTrace(url, options = {}) {
  const store = requestContext.getStore();
  const headers = {
    ...options.headers,
    "x-correlation-id": store?.correlationId ?? randomUUID(),
  };
  return fetch(url, { ...options, headers });
}

// The downstream service's own middleware will pick this up and reuse it.
await fetchWithTrace("https://billing.internal/charge", {
  method: "POST",
  body: JSON.stringify({ amount: 999 }),
});

Do the same for message queues — put the ID in the message metadata so async consumers stay on the same trace.

Step 4: Return It to the Client

Always expose the ID in responses (we did this with res.setHeader above) and in error bodies:

app.use((err, req, res, next) => {
  const id = requestContext.getStore()?.correlationId;
  log("error", err.message, { stack: err.stack });
  res.status(500).json({
    error: "internal_server_error",
    correlationId: id,
  });
});

Now when a user files a bug, they can paste the ID straight from the error response. You go from "saving failed" to the exact failing line in seconds.

A Few Practical Rules

Pick one header name and standardize it everywhere — x-correlation-id, x-request-id, or the W3C traceparent if you're adopting OpenTelemetry. Don't trust client-supplied IDs blindly: cap their length and strip anything that isn't alphanumeric/hyphen to avoid log-injection. And keep the ID opaque — it's for correlation, not for carrying user data.

Wrapping Up

Correlation IDs are one of the highest-leverage, lowest-effort changes you can make to an API: a few lines of middleware turn scattered, unjoinable logs into a single searchable thread per request. Generate at the edge, store in context, log everywhere, propagate downstream, and return it to the caller.

If you'd rather see correlation IDs flow through your endpoints without hand-rolling the plumbing, APIKumo lets you set request/response headers and pre/post-processors across an entire API collection — so you can inject and inspect trace headers on every call, share live docs that document them, and debug multi-service requests from one workspace.

Ship Your API Docs From the Terminal: A Tour of the New apikumo CLI

Mean — Thu, 18 Jun 2026 03:49:37 +0000

Spec-first development has one persistent leak: the moment your OpenAPI file and your published docs fall out of sync. You edit openapi.yaml, commit it, and then... someone has to remember to update the docs site. The new apikumo CLI (v0.3.0) closes that gap by making "publish my docs" a single terminal command you can wire into the same workflow that already tracks your spec.

It ships as a standalone binary — no Node.js runtime required — for macOS and Linux, with Windows on the way. Here's the full loop from install to a live, updated docs site.

Install

On macOS or Linux, the fastest path is Homebrew:

brew install apikumo/tap/apikumo
# later, to update:
brew upgrade apikumo

There's also a plain binary download if you'd rather not use a tap. Confirm it's on your PATH:

apikumo --version
# v0.3.0

Authenticate once

Login uses a device-code flow — the CLI prints a verification code and opens your browser to approve, so your password never touches the terminal. The token is stored in your system keychain (or ~/.apikumo/credentials) and can be revoked anytime from the dashboard.

apikumo login
# Press Enter to open browser… (use --no-prompt to skip this in scripts)

apikumo whoami
# email: you@example.com
# user_id: usr_…
# token_id: tok_…

whoami caches its result for an hour; pass --refresh to force a re-fetch from the server.

Bind a folder to a collection

apikumo init runs an interactive wizard: pick your org, workspace, and collection, then point it at the folder that holds your OpenAPI files. It writes a small .apikumo/config.json you commit alongside the spec.

apikumo init
# ? Select workspace › My Workspace
# ? Select collection › My API
# ✓ Config written to .apikumo/config.json

Now the repo knows which collection it publishes to — no flags to remember on every push.

Preview, then push

This is the part that makes it safe to automate. Run push with --dry-run first: it validates the spec and shows a diff of exactly what would change, persisting nothing.

apikumo push --dry-run
# validates openapi.yaml and prints the diff — no writes

Happy with the diff? Drop the flag and attach a note describing the change:

apikumo push --summary "Add pagination params to /orders"

Without --file, push discovers specs in your configured source folder and shows an interactive picker; point it at a single file when you want to be explicit:

apikumo push --file ./specs/orders.yaml --summary "Bump to v1.2"

Check state anytime with apikumo status, which prints your auth state, the bound collection ID, and the source folder with its file count.

Drop it into your workflow

Because every step is a flag-driven command, the natural move is a pre-push or CI check that validates the spec before it ever merges:

#!/usr/bin/env bash
# scripts/check-spec.sh — fail the build on an invalid or unexpected diff
set -euo pipefail
apikumo push --dry-run

Run that on pull requests to catch breaking spec changes early, then run a real apikumo push --summary "$GIT_COMMIT_MSG" on merge to main so your published docs are never more than one commit behind your spec.

A few housekeeping commands round it out: apikumo logout clears the stored token from the machine, and apikumo telemetry status|enable|disable controls the anonymous, no-personal-data usage counter.

Closing

A docs site that updates itself from the same OpenAPI file your code already depends on is the whole point of spec-first development — and a CLI is what turns that from a good intention into a one-line habit. If you want your terminal (and your CI) to keep your API docs honest, the APIKumo CLI gives you init, a --dry-run preview, and a single push that ships typed, searchable docs to your own subdomain. Grab the binary, run apikumo init, and let the spec be the source of truth.

Sunset Your API Endpoints on Purpose: The Deprecation and Sunset Headers

Mean — Wed, 17 Jun 2026 02:20:08 +0000

Killing an API endpoint is easy. Killing it without breaking your consumers is the hard part. Most teams announce a deprecation in a blog post, send one email, and then act surprised when integrations break six months later. The clients that broke never read the blog post — but their code reads your HTTP responses on every single request. That's where the deprecation notice belongs.

Two standardized headers let you signal the full lifecycle of an endpoint directly in the response: Deprecation and Sunset. Used together, they turn a silent breaking change into a loud, machine-readable countdown.

The two headers

The Sunset header (RFC 8594) tells clients the date and time after which the resource is expected to stop working. The Deprecation header (an IETF draft, but widely adopted) tells clients that the resource is deprecated now — optionally with the date it became deprecated.

HTTP/1.1 200 OK
Content-Type: application/json
Deprecation: Sun, 01 Nov 2026 00:00:00 GMT
Sunset: Wed, 01 Apr 2027 00:00:00 GMT
Link: <https://api.example.com/docs/migrating-to-v2>; rel="deprecation"; type="text/html"

The Link header with rel="deprecation" points to human-readable migration docs. Together these say: this endpoint was deprecated on Nov 1, it will be removed on Apr 1, and here's how to migrate.

Adding it on the server

You don't need a framework feature — it's just response headers. Here's a small Express middleware you can attach to any route group you're retiring:

function deprecate({ deprecatedOn, sunsetOn, docs }) {
  const dep = new Date(deprecatedOn).toUTCString();
  const sun = new Date(sunsetOn).toUTCString();
  return (req, res, next) => {
    res.set("Deprecation", dep);
    res.set("Sunset", sun);
    res.set("Link", `<${docs}>; rel="deprecation"; type="text/html"`);
    next();
  };
}

app.use(
  "/v1/orders",
  deprecate({
    deprecatedOn: "2026-11-01",
    sunsetOn: "2027-04-01",
    docs: "https://api.example.com/docs/migrating-to-v2",
  })
);

In FastAPI it's just as small:

from fastapi import APIRouter, Response

router = APIRouter()

@router.get("/v1/orders")
def list_orders(response: Response):
    response.headers["Deprecation"] = "Sun, 01 Nov 2026 00:00:00 GMT"
    response.headers["Sunset"] = "Wed, 01 Apr 2027 00:00:00 GMT"
    response.headers["Link"] = (
        '<https://api.example.com/docs/migrating-to-v2>; '
        'rel="deprecation"; type="text/html"'
    )
    return {"orders": []}

Reading it on the client

The whole point is that consumers can detect the countdown automatically. A thin wrapper around fetch can warn the moment a deprecated endpoint is touched:

async function apiFetch(url, options) {
  const res = await fetch(url, options);
  const sunset = res.headers.get("Sunset");
  if (res.headers.get("Deprecation") || sunset) {
    const when = sunset ? ` Removal: ${sunset}.` : "";
    console.warn(`[deprecated] ${url} is deprecated.${when}`);
  }
  return res;
}

Pipe that warning into your logging or alerting stack and a deprecation stops being something a human has to remember — your CI logs start nagging you the day the header appears.

Doing it right

A few rules make the difference between a smooth retirement and an angry support queue. Set the Sunset date far enough out to be realistic — months, not weeks — and never move it closer once published. Keep returning real data until the sunset date; the headers are a warning, not a 410 Gone. Always include the Link to migration docs, because a date with no instructions just creates panic. And monitor traffic to the deprecated endpoint so you know whether anyone is actually still calling it before you pull the plug.

Closing

Deprecation headers are a small addition with an outsized payoff: every response becomes self-documenting about its own expiry, and your consumers get a programmatic heads-up instead of a nasty surprise. The hard part is staying consistent — applying the headers everywhere, keeping the dates accurate, and verifying clients actually see them. That's the kind of cross-cutting API concern a tool like APIKumo is built for: you can inspect response headers across every endpoint, script checks that assert your Deprecation and Sunset values are present and correct, and document the migration path right alongside the live API. Sunset your endpoints on purpose — not by accident.

Timeouts and Circuit Breakers: Stop One Slow API From Taking Down Your Whole App

Mean — Tue, 16 Jun 2026 02:07:55 +0000

When you call another service over HTTP, you are inheriting its worst day. If that dependency slows to a crawl, every request you make to it piles up, holds a connection, and eventually drags your service down with it. The fix is two old, unglamorous patterns: aggressive timeouts and a circuit breaker. Here is how to implement both in Node.js with no framework.

Step 1: Never make a request without a timeout

The single most common production incident is a missing timeout. By default, most HTTP clients will wait forever. One stalled dependency is enough to exhaust your connection pool.

async function fetchWithTimeout(url, { timeoutMs = 2000, ...options } = {}) {
  const controller = new AbortController();
  const timer = setTimeout(() => controller.abort(), timeoutMs);
  try {
    return await fetch(url, { ...options, signal: controller.signal });
  } finally {
    clearTimeout(timer);
  }
}

AbortController gives you a hard ceiling. If the dependency hasn't answered in 2 seconds, you fail fast and free the connection instead of letting it hang.

Step 2: Stop hammering a service that's already down

Timeouts protect a single request. But if a dependency is fully down, retrying every call still wastes 2 seconds each and keeps the pressure on. A circuit breaker tracks failures and, once they cross a threshold, "opens" — rejecting calls instantly without even trying the network. After a cooldown it lets one probe request through to see if the service has recovered.

class CircuitBreaker {
  constructor({ failureThreshold = 5, cooldownMs = 10000 } = {}) {
    this.failureThreshold = failureThreshold;
    this.cooldownMs = cooldownMs;
    this.failures = 0;
    this.state = 'CLOSED';      // CLOSED | OPEN | HALF_OPEN
    this.nextAttempt = 0;
  }

  async call(fn) {
    if (this.state === 'OPEN') {
      if (Date.now() < this.nextAttempt) {
        throw new Error('Circuit is OPEN — failing fast');
      }
      this.state = 'HALF_OPEN'; // time to test the waters
    }

    try {
      const result = await fn();
      this.onSuccess();
      return result;
    } catch (err) {
      this.onFailure();
      throw err;
    }
  }

  onSuccess() {
    this.failures = 0;
    this.state = 'CLOSED';
  }

  onFailure() {
    this.failures += 1;
    if (this.failures >= this.failureThreshold) {
      this.state = 'OPEN';
      this.nextAttempt = Date.now() + this.cooldownMs;
    }
  }
}

Step 3: Wire them together

Now combine the timeout and the breaker. The breaker wraps the timed request, so a slow dependency counts as a failure and eventually trips the circuit.

const breaker = new CircuitBreaker({ failureThreshold: 5, cooldownMs: 10000 });

async function getUser(id) {
  return breaker.call(async () => {
    const res = await fetchWithTimeout(`https://api.example.com/users/${id}`, {
      timeoutMs: 2000,
    });
    if (!res.ok) throw new Error(`Upstream returned ${res.status}`);
    return res.json();
  });
}

The three states tell the whole story:

CLOSED — normal operation, requests flow through and failures are counted.
OPEN — too many failures; calls are rejected instantly for the cooldown window.
HALF_OPEN — one probe request is allowed; success closes the circuit, failure re-opens it.

Step 4: Always have a fallback

Failing fast is only useful if you have something to do with the failure. Degrade gracefully instead of returning a 500.

async function getUserSafe(id) {
  try {
    return await getUser(id);
  } catch (err) {
    // Serve stale cache, a default, or a partial response
    return { id, name: 'Unknown', degraded: true };
  }
}

A few rules that keep this honest

Set timeouts based on real latency percentiles, not a guess — start near the p99 of the dependency and tune. Keep one breaker per dependency, never a global one, or a single sick service will trip calls to healthy ones. And always log state transitions: an OPEN circuit is one of the highest-signal alerts you can have, because it tells you a dependency is failing before your users start complaining.

Timeouts and circuit breakers are about ten lines of code each, and together they turn a cascading outage into a localized, recoverable blip.

Testing resilience behavior by hand is tedious — you need to simulate slow responses, forced errors, and recovery. APIKumo makes it easy to mock failing and slow endpoints, script multi-step request flows, and replay them so you can watch your timeouts and breaker actually trip before you ship them to production.

Server-Sent Events: The Simplest Way to Stream Data From Your API

Mean — Mon, 15 Jun 2026 02:26:29 +0000

Why SSE Instead of WebSockets or Polling?

If your API needs to push data to clients as it becomes available — progress updates, live logs, notifications, or token-by-token LLM output — you have three options: short polling, WebSockets, or Server-Sent Events.

Polling is wasteful: the client repeatedly asks "anything new?" and usually hears "no." WebSockets are powerful but bidirectional and stateful, which is overkill when only the server needs to talk. SSE sits in the sweet spot: a single long-lived HTTP response that streams text events from server to client, with automatic reconnection built into the browser.

Because SSE is just HTTP, it works through proxies and load balancers, needs no special protocol upgrade, and is trivial to authenticate with the headers you already use.

The Wire Format

SSE is astonishingly simple. The server responds with Content-Type: text/event-stream and writes plain-text blocks separated by blank lines:

event: message
data: {"progress": 25}

event: message
data: {"progress": 50}

event: done
data: {"status": "complete"}

Each field is name: value. The important ones are data, event (a custom event name), id (used for resuming), and retry (reconnect delay in ms). A blank line dispatches the event.

A Streaming Endpoint in Node

Here is a complete, working SSE endpoint using Express. It streams a counter and then closes:

import express from "express";

const app = express();

app.get("/events", (req, res) => {
  res.writeHead(200, {
    "Content-Type": "text/event-stream",
    "Cache-Control": "no-cache",
    "Connection": "keep-alive",
  });

  let count = 0;
  const timer = setInterval(() => {
    count += 1;
    res.write(`event: tick\n`);
    res.write(`id: ${count}\n`);
    res.write(`data: ${JSON.stringify({ count })}\n\n`);

    if (count >= 5) {
      res.write(`event: done\ndata: {}\n\n`);
      clearInterval(timer);
      res.end();
    }
  }, 1000);

  // Always clean up when the client disconnects
  req.on("close", () => clearInterval(timer));
});

app.listen(3000, () => console.log("SSE server on :3000"));

Two details matter. First, you must disable buffering (Cache-Control: no-cache) or proxies may hold your events. Second, always handle req.on("close") — without it, abandoned connections leak timers and memory.

Consuming It in the Browser

The browser ships with EventSource, which handles parsing and reconnection for you:

const source = new EventSource("/events");

source.addEventListener("tick", (e) => {
  const { count } = JSON.parse(e.data);
  console.log("tick", count);
});

source.addEventListener("done", () => {
  console.log("stream finished");
  source.close();
});

source.onerror = (err) => console.error("connection error", err);

If the connection drops, EventSource automatically reconnects and sends a Last-Event-ID header containing the last id it saw — so your server can resume from where it left off.

Consuming It Outside the Browser

EventSource doesn't support custom headers, which is a problem for authenticated APIs. In Node or any backend, use fetch and parse the stream yourself:

const res = await fetch("https://api.example.com/events", {
  headers: { Authorization: `Bearer ${token}` },
});

const reader = res.body.getReader();
const decoder = new TextDecoder();
let buffer = "";

while (true) {
  const { value, done } = await reader.read();
  if (done) break;
  buffer += decoder.decode(value, { stream: true });

  const events = buffer.split("\n\n");
  buffer = events.pop();               // keep the incomplete trailing chunk

  for (const block of events) {
    const dataLine = block.split("\n").find((l) => l.startsWith("data:"));
    if (dataLine) console.log("event", JSON.parse(dataLine.slice(5).trim()));
  }
}

This same pattern is exactly how OpenAI-style streaming completions are consumed — they are SSE under the hood.

Gotchas Worth Knowing

Keep connections alive through idle proxies by sending a comment line (: keep-alive\n\n) every 15–30 seconds. Browsers cap SSE to six concurrent connections per domain over HTTP/1.1, so prefer HTTP/2 if clients open many streams. And SSE only carries UTF-8 text — to send binary, base64-encode it.

Testing Streaming Endpoints

Streaming endpoints are harder to test than request/response ones because the output arrives in pieces over time. A good API workspace like APIKumo lets you fire a request at an text/event-stream endpoint and watch events arrive live, inspect each data frame, and save the call alongside the rest of your collection — so verifying that your SSE stream emits the right events becomes a one-click check instead of a custom script. Once your streaming contract is captured there, the whole team can replay it the same way.

Async APIs: The 202 Accepted + Polling Pattern for Long-Running Operations

Mean — Sun, 14 Jun 2026 03:24:41 +0000

Some API requests can't finish in time for a single HTTP response. Generating a report, transcoding a video, running a batch import — these take seconds or minutes, far longer than any client should hold a connection open for. If you try to do this work inside a normal request, you'll hit gateway timeouts, frustrated clients retrying half-finished jobs, and load balancers killing connections at 30 or 60 seconds.

The fix is a well-established HTTP pattern: accept the work, hand back a receipt, and let the client poll for the result. Here's how to build it properly.

The shape of the pattern

The client POSTs the job. The server validates it, enqueues it, and immediately returns 202 Accepted with a URL where the status lives.
The client polls that status URL until the job is done (or failed).
When complete, the status response points to the finished resource.

The key detail most implementations get wrong: 202 does not mean "success." It means "I accepted this and will work on it." The actual outcome arrives later.

Step 1: Accept the job

import express from "express";
import { randomUUID } from "crypto";

const app = express();
app.use(express.json());
const jobs = new Map(); // use Redis or a DB in production

app.post("/v1/reports", (req, res) => {
  const id = randomUUID();
  jobs.set(id, { status: "pending", createdAt: Date.now(), result: null });

  // Kick off work without blocking the response
  processReport(id, req.body).catch((err) => {
    jobs.set(id, { status: "failed", error: err.message });
  });

  res
    .status(202)
    .location(`/v1/reports/${id}`)
    .json({ id, status: "pending" });
});

Notice the Location header. It tells the client exactly where to look — no need to construct the URL itself.

Step 2: Expose a status endpoint

app.get("/v1/reports/:id", (req, res) => {
  const job = jobs.get(req.params.id);
  if (!job) return res.status(404).json({ error: "unknown job" });

  if (job.status === "done") {
    // Redirect to the finished resource, or inline it
    return res.status(303).location(`/v1/reports/${req.params.id}/result`).end();
  }

  // Still working: tell the client when to check again
  res.set("Retry-After", "5");
  res.json({ id: req.params.id, status: job.status });
});

The Retry-After: 5 header is the polite, machine-readable way to say "check back in 5 seconds." A 303 See Other on completion sends the client to the real result so the status URL and the result URL stay cleanly separated.

Step 3: Poll from the client

Don't hammer the server in a tight loop. Honor Retry-After and cap your wait:

async function waitForJob(url, { timeoutMs = 120000 } = {}) {
  const deadline = Date.now() + timeoutMs;

  while (Date.now() < deadline) {
    const res = await fetch(url, { redirect: "manual" });

    if (res.status === 303) {
      const resultUrl = res.headers.get("location");
      return fetch(resultUrl).then((r) => r.json());
    }
    if (res.status >= 400) throw new Error(`Job failed: ${res.status}`);

    const wait = Number(res.headers.get("retry-after") || 3) * 1000;
    await new Promise((r) => setTimeout(r, wait));
  }
  throw new Error("Timed out waiting for job");
}

const { id } = await fetch("/v1/reports", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ range: "2026-Q1" }),
}).then((r) => r.json());

const report = await waitForJob(`/v1/reports/${id}`);

Practical details that bite you

Make status checks idempotent and cheap. They'll be called far more often than the job runs. A single key lookup, no recomputation.

Return progress when you can. A { status: "running", progress: 0.6 } field turns a black box into a progress bar.

Expire finished jobs. Don't keep job records forever. Give status URLs a TTL and return 410 Gone once cleaned up.

Consider webhooks as an alternative. Polling is simple and firewall-friendly, but if the client can receive callbacks, a webhook on completion saves a lot of wasted requests. Many APIs offer both.

Closing

The 202-and-poll pattern keeps long-running work off your request path without surprising clients. Get the status codes, the Location and Retry-After headers, and the polling discipline right, and async endpoints feel just as predictable as synchronous ones.

Testing async flows is fiddly — you're juggling a POST, repeated GETs, and timing-dependent state transitions. APIKumo makes this easier: you can chain the initial request and the polling calls in a single flow, capture the job ID into a variable with a post-processor, and replay the whole sequence whenever you change the endpoint — so verifying your long-running operations becomes a one-click check instead of a manual stopwatch exercise.

API Mocking: Build and Test Against Endpoints That Don't Exist Yet

Mean — Thu, 11 Jun 2026 08:04:32 +0000

Stop Blocking on the Backend: API Mocking for Faster Frontend Development

Every team has lived this: the frontend is ready to build the checkout screen, but the /orders endpoint won't ship for another two weeks. So work stalls, or someone hard-codes a fake response that quietly rots until integration day — when nothing matches and everyone blames each other.

API mocking fixes this. A mock server returns realistic responses for endpoints that don't exist yet (or are flaky, slow, or rate-limited), so consumers can build and test against a stable contract. Here's how to do it well.

Start From the Contract, Not From Guesses

The worst mocks are invented by hand and drift from reality. The best ones are generated from the same OpenAPI spec the real API will implement. That way the mock is the contract.

A minimal spec for one endpoint:

# openapi.yaml
openapi: 3.0.3
info: { title: Orders API, version: 1.0.0 }
paths:
  /orders/{id}:
    get:
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: An order
          content:
            application/json:
              schema:
                type: object
                properties:
                  id: { type: string, example: "ord_123" }
                  status: { type: string, example: "shipped" }
                  total_cents: { type: integer, example: 4999 }

Tools like Prism turn that directly into a running server:

npx @stoplight/prism-cli mock openapi.yaml
# → Prism is listening on http://127.0.0.1:4010

curl http://127.0.0.1:4010/orders/ord_123
# {"id":"ord_123","status":"shipped","total_cents":4999}

No backend, no database — but a response that's guaranteed to match the documented schema.

Roll Your Own When You Need Control

Sometimes you want custom logic: simulate latency, return different payloads per ID, or flip an endpoint into an error state on demand. A tiny Express server does the job:

// mock-server.js
const express = require("express");
const app = express();

const orders = {
  ord_123: { id: "ord_123", status: "shipped", total_cents: 4999 },
  ord_456: { id: "ord_456", status: "pending", total_cents: 1200 },
};

app.get("/orders/:id", (req, res) => {
  const order = orders[req.params.id];
  if (!order) {
    return res.status(404).json({
      type: "https://errors.example.com/not-found",
      title: "Order not found",
      status: 404,
    });
  }
  // Simulate a slow downstream so you can test loading states
  setTimeout(() => res.json(order), 300);
});

app.listen(4010, () => console.log("Mock on http://localhost:4010"));

Now your frontend can exercise the 200 path, the 404 path, and the spinner — all before a single line of real backend code exists.

Mock at the Network Layer in Tests

For unit and integration tests, don't spin up a server at all — intercept requests in-process. Mock Service Worker (MSW) does this cleanly and runs in both Node and the browser:

import { setupServer } from "msw/node";
import { http, HttpResponse } from "msw";

const server = setupServer(
  http.get("https://api.example.com/orders/:id", ({ params }) => {
    return HttpResponse.json({
      id: params.id,
      status: "shipped",
      total_cents: 4999,
    });
  })
);

beforeAll(() => server.listen());
afterEach(() => server.resetHandlers());
afterAll(() => server.close());

test("renders shipped order", async () => {
  const res = await fetch("https://api.example.com/orders/ord_123");
  const body = await res.json();
  expect(body.status).toBe("shipped");
});

Because MSW intercepts at the network boundary, your application code uses the real fetch — no special test-only branches polluting production logic.

Keep Mocks Honest

A mock that drifts from the real API is worse than no mock at all, because it builds false confidence. Three habits keep them trustworthy:

Generate from the spec so the schema is always authoritative.
Validate the real API against the same spec in CI, so the contract stays a two-way promise.
Mock failure modes, not just happy paths — 429s, 500s, timeouts, and partial data are where real bugs hide.

Wrapping Up

API mocking decouples teams, shrinks feedback loops, and lets you test the ugly edge cases that are painful to reproduce against a live service. The key is to anchor your mocks to a single source of truth so they never quietly diverge from reality.

If you'd rather not stitch together separate tools for specs, mock servers, and request testing, APIKumo lets you design an API collection, generate a mock endpoint from it, and validate requests against the same definition — so your mock and your real API stay in sync as the contract evolves.

Spec-First API Development: Make Your OpenAPI File the Source of Truth

Mean — Wed, 10 Jun 2026 03:02:41 +0000

Spec-First API Development: Make Your OpenAPI File the Source of Truth

Most teams write the API first and the spec later — if ever. The code ships, the OpenAPI document drifts, and six months on the docs describe an API that no longer exists. Spec-first flips the order: you design the contract in OpenAPI before writing a single route, then generate mocks, validation, docs, and clients from that one file. The spec stops being documentation and becomes the source of truth.

Here's how to actually do it.

1. Design the contract first

Start with a minimal but precise OpenAPI 3.1 document. Describe the shape of requests and responses, not the implementation.

# openapi.yaml
openapi: 3.1.0
info:
  title: Orders API
  version: 1.0.0
paths:
  /orders/{id}:
    get:
      operationId: getOrder
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        "200":
          description: The order
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Order" }
        "404":
          description: Not found
components:
  schemas:
    Order:
      type: object
      required: [id, status, total]
      properties:
        id: { type: string }
        status: { type: string, enum: [pending, paid, shipped] }
        total: { type: number }

Because this is written before the code, frontend and backend can agree on the contract on day one instead of arguing about field names in code review.

2. Mock the API before it exists

Your frontend team shouldn't wait for the backend. Point a mock server at the spec and they can build against realistic responses immediately. Prism does this with zero code:

npx @stoplight/prism-cli mock openapi.yaml
# GET http://127.0.0.1:4010/orders/123
# → { "id": "string", "status": "pending", "total": 0 }

Prism validates incoming requests against the spec and returns spec-compliant responses. If the frontend sends a malformed request, it fails against the mock — long before it ever hits real infrastructure.

3. Enforce the contract at runtime

The biggest risk with spec-first is drift: the code quietly diverges from the document. Stop that by validating live traffic against the spec. With Express:

const express = require("express");
const OpenApiValidator = require("express-openapi-validator");

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

app.use(
  OpenApiValidator.middleware({
    apiSpec: "./openapi.yaml",
    validateRequests: true,
    validateResponses: true, // catches drift in YOUR responses too
  })
);

app.get("/orders/:id", (req, res) => {
  res.json({ id: req.params.id, status: "paid", total: 42.0 });
});

// Spec violations become clean 400/500s instead of silent bugs
app.use((err, req, res, next) => {
  res.status(err.status || 500).json({ message: err.message });
});

app.listen(3000);

validateResponses: true is the part most people skip — and it's the part that matters. It fails loudly in tests when your handler returns a field the spec doesn't allow, so the code can never silently outrun the contract.

4. Generate clients instead of hand-writing them

Once the spec is authoritative, typed clients are a build step, not a chore:

npx openapi-typescript openapi.yaml -o src/api-types.ts

Now your frontend gets compile-time errors the moment a response shape changes in the spec. No more guessing whether total is a string or a number.

Why this order matters

Spec-first works because every artifact flows from one file: mocks for parallel work, runtime validation to prevent drift, generated types for safety, and always-accurate docs. Change the spec, regenerate everything, and your whole stack stays in sync.

The friction is usually tooling sprawl — a mock server here, a validator there, a docs generator somewhere else, all pointed at copies of a spec that slowly diverge. APIKumo keeps the spec, live versioned docs, mock environments, and generated client code in one workspace, so the contract you design is the contract your team builds against. Define it once, and let everything else follow.

Contract Testing: Catch Breaking API Changes Before Your Consumers Do

Mean — Mon, 08 Jun 2026 03:53:40 +0000

Ever shipped a backend change that passed every test, only to wake up to a frontend on fire? The API still returned 200 OK — it just renamed user_name to username, and three consumers broke silently. Unit tests didn't catch it. Integration tests didn't catch it. This is exactly the gap contract testing fills.

What a contract actually is

A contract is a machine-readable agreement about the shape of requests and responses between a consumer (the client) and a provider (the API). Instead of testing the provider in isolation and hoping clients agree, the consumer declares what it needs, and the provider proves it still delivers.

In consumer-driven contract testing, the consumer owns the contract. The provider's job is to never break it without a conversation.

A minimal contract test

You don't need a heavyweight framework to start. Here's a contract expressed as a plain JSON schema that both sides can share.

{
  "request": { "method": "GET", "path": "/users/42" },
  "response": {
    "status": 200,
    "body": {
      "type": "object",
      "required": ["id", "username", "email"],
      "properties": {
        "id":       { "type": "integer" },
        "username": { "type": "string" },
        "email":    { "type": "string", "format": "email" }
      }
    }
  }
}

The consumer verifies it can rely on these fields. The provider verifies its real output still satisfies them.

Verifying on the provider side

Run the contract against the live provider response in CI using Ajv, a fast JSON Schema validator:

import Ajv from "ajv";
import addFormats from "ajv-formats";
import contract from "./contracts/get-user.json" assert { type: "json" };

const ajv = addFormats(new Ajv({ allErrors: true }));
const validate = ajv.compile(contract.response.body);

test("GET /users/:id honors the consumer contract", async () => {
  const res = await fetch("http://localhost:3000/users/42");

  expect(res.status).toBe(contract.response.status);

  const body = await res.json();
  const ok = validate(body);

  if (!ok) console.error(validate.errors);
  expect(ok).toBe(true);
});

Now rename username back to user_name on the provider and this test fails before the change merges — not after a consumer pages you at 2 a.m.

Why this beats a shared staging environment

The classic alternative is end-to-end tests against a shared environment. They're slow, flaky, and only catch breakage after both services deploy together. Contract tests run in milliseconds, in isolation, and pin down responsibility: if the contract test goes red, the provider broke it.

Critically, contracts catch additive-but-breaking changes that loose typing hides — a field changing from integer to string, a required field going optional, an enum dropping a value. Your provider's own tests pass because the provider is internally consistent. The contract is the only thing watching the boundary.

Make breaking changes a deliberate act

The real payoff is workflow. Commit contracts to a repo both teams can see. Wire provider verification into the provider's pipeline. When a provider change violates a contract, CI fails and forces the question: do we version this, or coordinate the migration?

# .github/workflows/contracts.yml
name: contract-tests
on: [pull_request]
jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 20 }
      - run: npm ci
      - run: npm run start:provider &
      - run: npx wait-on http://localhost:3000/health
      - run: npm test -- contracts/

Breaking the contract becomes a conscious decision with a paper trail, not an accident.

Getting started without the ceremony

You can adopt this incrementally: start with your two or three most depended-on endpoints, write a schema for each, and fail the build when reality drifts. Add more as confidence grows. Tools like Pact add a broker and versioning once you outgrow plain schemas — but the principle is the same at every scale.

If you'd rather not hand-roll the schemas and CI glue, APIKumo lets you capture request/response shapes from your existing collections, keep them versioned alongside live docs, and run them as checks — so the contract stays in lockstep with the API your consumers actually call. Whichever route you take, the goal is the same: catch the break before your users do.

Stop Inventing Your Own API Error Format: Use RFC 9457 Problem Details

Mean — Sat, 06 Jun 2026 02:06:49 +0000

Stop Inventing Your Own API Error Format: Use RFC 9457 Problem Details

Every API eventually grows its own snowflake error format. One endpoint returns {"error": "not found"}, another returns {"message": "Not Found", "code": 404}, and a third buries the real reason in a 200 OK with {"success": false}. Clients end up writing brittle, per-endpoint parsing logic just to figure out what went wrong.

There is a standard that fixes this: RFC 9457 — Problem Details for HTTP APIs (the update to the older RFC 7807). It defines a single, predictable JSON shape for errors, with a registered media type. If you adopt it, any client — including generic tooling — can understand your errors without custom code.

The shape

A Problem Details response uses the application/problem+json content type and a small set of standard fields:

{
  "type": "https://example.com/probs/insufficient-funds",
  "title": "Insufficient funds",
  "status": 403,
  "detail": "Your balance is 30 but the transfer requires 50.",
  "instance": "/accounts/12345/transfers/abc",
  "balance": 30,
  "required": 50
}

The fields mean:

type — a URI identifying the kind of problem. It doubles as documentation.
title — a short, human-readable summary that stays constant for a given type.
status — the HTTP status code, repeated in the body for convenience.
detail — a human-readable explanation specific to this occurrence.
instance — a URI identifying the specific occurrence.

You can add extension members (balance, required above) so machines can act on the error programmatically, not just display it.

Producing it in Express

Here is a tiny helper plus an example route. No framework magic required:

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

function problem(res, { type = "about:blank", title, status, detail, instance, ...extra }) {
  res
    .status(status)
    .type("application/problem+json")
    .json({ type, title, status, detail, instance, ...extra });
}

app.post("/accounts/:id/transfers", (req, res) => {
  const balance = 30;
  const amount = req.body.amount ?? 0;

  if (amount > balance) {
    return problem(res, {
      type: "https://api.example.com/probs/insufficient-funds",
      title: "Insufficient funds",
      status: 403,
      detail: `Your balance is ${balance} but the transfer requires ${amount}.`,
      instance: req.originalUrl,
      balance,
      required: amount,
    });
  }

  res.status(201).json({ ok: true });
});

app.listen(3000);

The about:blank default for type is exactly what the spec recommends when you have nothing more specific to say — it means "the status code is the whole story."

Validation errors are where it shines

Most APIs return their ugliest errors on validation. Problem Details handles this cleanly with an extension array:

{
  "type": "https://api.example.com/probs/validation-error",
  "title": "Your request body is invalid",
  "status": 422,
  "errors": [
    { "field": "email", "detail": "must be a valid email address" },
    { "field": "age", "detail": "must be >= 18" }
  ]
}

Because errors is a documented extension, every client can render field-level messages the same way across every endpoint.

Consuming it on the client

The payoff is a single, reusable error handler:

async function callApi(url, options) {
  const res = await fetch(url, options);
  if (res.ok) return res.json();

  const ct = res.headers.get("content-type") || "";
  if (ct.includes("application/problem+json")) {
    const p = await res.json();
    throw new Error(`${p.title} (${p.status}): ${p.detail ?? ""}`);
  }
  throw new Error(`Request failed: ${res.status}`);
}

One handler, every endpoint, no per-route special cases.

A few practical rules

Keep type URIs stable — clients may branch on them, so treat them as part of your public contract. Never put sensitive data in detail, since it's meant to be shown to users. And always set the real HTTP status code; the body mirrors it, but proxies, caches, and monitoring still rely on the status line.

Closing

Adopting a standard error format is one of the cheapest reliability upgrades you can make, but it only helps if it's applied consistently across every endpoint — which is hard to enforce by hand. This is where a workspace like APIKumo helps: you can define, send, and document requests in one place, capture real problem+json responses as examples, and keep your error contract consistent as your API grows. Standardize the shape once, and every future client — and every future you — gets to stop guessing.

ETags and Conditional Requests: Stop Sending the Same API Response Twice

Mean — Fri, 05 Jun 2026 02:07:04 +0000

Your API Is Sending the Same Bytes Over and Over

Most APIs re-serialize and re-send identical payloads thousands of times a day. The client already has the data, the data hasn't changed, and yet every request burns a full round trip plus bandwidth plus database time. HTTP solved this in 1999 with conditional requests — and most APIs still don't use them.

This post shows you how to add ETag and Cache-Control to a REST API so clients can ask "has anything changed?" and get a tiny 304 Not Modified instead of the whole body.

The Two Headers That Do the Work

Cache-Control tells the client how long a response stays fresh. ETag is a fingerprint of the response body that lets the client revalidate once it goes stale. Together they let a client skip the network entirely while fresh, then revalidate cheaply afterward.

A typical exchange looks like this:

GET /api/products/42 HTTP/1.1

HTTP/1.1 200 OK
Cache-Control: private, max-age=60
ETag: "a1b2c3d4"
Content-Type: application/json

{ "id": 42, "name": "Wireless Mouse", "price": 1999 }

On the next request, the client sends the fingerprint back:

GET /api/products/42 HTTP/1.1
If-None-Match: "a1b2c3d4"

HTTP/1.1 304 Not Modified
ETag: "a1b2c3d4"

No body. No serialization. Often no database read. Just a few dozen bytes confirming "you already have it."

Implementing It in Express

Here's a small Node/Express handler that generates a strong ETag from the response content and short-circuits on a match.

import express from "express";
import crypto from "node:crypto";

const app = express();

function makeETag(payload) {
  const json = JSON.stringify(payload);
  const hash = crypto.createHash("sha1").update(json).digest("base64url");
  return `"${hash}"`;
}

app.get("/api/products/:id", async (req, res) => {
  const product = await db.getProduct(req.params.id);
  if (!product) return res.sendStatus(404);

  const etag = makeETag(product);
  res.set("Cache-Control", "private, max-age=60");
  res.set("ETag", etag);

  // Client already has this exact version → revalidate cheaply
  if (req.headers["if-none-match"] === etag) {
    return res.status(304).end();
  }

  res.json(product);
});

The key detail: you still load the object to compute its ETag here, but you skip JSON serialization and the network payload. To skip the database read too, store a version column or updated_at timestamp and build the ETag from that instead of the full body:

const meta = await db.getProductVersion(req.params.id); // cheap row
const etag = `"${meta.id}-${meta.version}"`;
if (req.headers["if-none-match"] === etag) return res.status(304).end();

const product = await db.getProduct(req.params.id); // only when changed
res.set("ETag", etag).json(product);

Don't Forget Writes

ETags aren't just for reads. The same fingerprint powers optimistic concurrency on updates via If-Match, which stops two clients from silently overwriting each other:

app.put("/api/products/:id", async (req, res) => {
  const current = await db.getProductVersion(req.params.id);
  const etag = `"${current.id}-${current.version}"`;

  if (req.headers["if-match"] && req.headers["if-match"] !== etag) {
    return res.status(412).send("Precondition Failed"); // stale write
  }
  const updated = await db.updateProduct(req.params.id, req.body);
  res.set("ETag", `"${updated.id}-${updated.version}"`).json(updated);
});

A 412 here means "someone changed this since you last read it" — the client refetches and retries instead of clobbering data.

Picking Cache-Control Directives

A few rules that cover most APIs:

private for anything user-specific so shared proxies don't cache it.
no-cache when you want clients to always revalidate with the ETag (it does not mean "don't cache").
max-age=0, must-revalidate for data that's sensitive to staleness but still benefits from ETag revalidation.
public, max-age=3600 only for genuinely shared, non-personalized resources.

Closing

Conditional requests are one of the highest-leverage, lowest-effort wins in API performance: a few headers turn repeated full responses into near-empty 304s and protect your writes from race conditions for free. The hard part is usually testing it — eyeballing If-None-Match and If-Match behavior across endpoints by hand is tedious. That's where APIKumo helps: you can define requests in a shared workspace, capture an ETag from one call, and feed it straight into the next request's If-None-Match or If-Match header with pre/post processors — so verifying that your caching and concurrency logic actually returns 304 and 412 takes seconds, not a debugging session.