DEV Community: APIKumo

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.

Idempotency Keys: The One API Pattern That Prevents Duplicate Charges (and Worse)

Mean — Thu, 04 Jun 2026 02:06:52 +0000

You hit "Pay" and the browser spins. Network timeout. Did the charge go through? You retry — and get charged twice.

Idempotency keys solve this. They're one of the most important API patterns you can implement, and they're still missing from most homegrown APIs.

What Is an Idempotency Key?

An idempotency key is a unique client-generated token attached to a request. If the server receives the same key twice, it returns the same result as the first request without re-executing the operation.

Stripe pioneered this pattern for payments. The concept is now widespread across financial, messaging, and any API where duplicate side effects are dangerous.

How It Works

The flow is simple:

Client generates a unique key (UUID v4 is standard)
Client sends the key in a request header: Idempotency-Key: <uuid>
Server checks its store — has this key been seen before?
- No → Execute the operation, store the result against the key, return result
- Yes → Return the stored result immediately, no re-execution

POST /payments
Idempotency-Key: f47ac10b-58cc-4372-a567-0e02b2c3d479
Content-Type: application/json

{"amount": 2000, "currency": "usd", "customer_id": "cus_abc123"}

Retry that request 10 times with the same key — the charge happens exactly once.

Server Implementation (Node.js / Express)

const express = require("express");
const { createClient } = require("redis");
const { v4: uuidv4 } = require("uuid");

const app = express();
const redis = createClient();
await redis.connect();

app.post("/payments", async (req, res) => {
  const idempotencyKey = req.headers["idempotency-key"];

  if (!idempotencyKey) {
    return res.status(400).json({ error: "Idempotency-Key header is required" });
  }

  // Check if we've seen this key before
  const cached = await redis.get(`idempotency:${idempotencyKey}`);
  if (cached) {
    return res.status(200).json(JSON.parse(cached));
  }

  // Process the payment
  const result = await processPayment(req.body);

  // Store result with a 24-hour TTL
  await redis.setEx(
    `idempotency:${idempotencyKey}`,
    86400,
    JSON.stringify(result)
  );

  return res.status(201).json(result);
});

Key implementation details:

Store in Redis (or a DB), not in-memory — you'll have multiple server instances
Set a TTL — 24 hours to 7 days is typical; clear old keys eventually
Return the exact same HTTP status code on replays, not just 200
Lock during processing to handle concurrent requests with the same key (use Redis SET NX or a DB transaction)

Client Implementation

import httpx
import uuid

def create_payment(amount: int, currency: str, customer_id: str) -> dict:
    idempotency_key = str(uuid.uuid4())

    for attempt in range(3):
        try:
            response = httpx.post(
                "https://api.example.com/payments",
                headers={"Idempotency-Key": idempotency_key},
                json={"amount": amount, "currency": currency, "customer_id": customer_id},
                timeout=10.0
            )
            response.raise_for_status()
            return response.json()
        except httpx.TimeoutException:
            if attempt == 2:
                raise
            # Same key on retry — safe to resend
            continue

    raise RuntimeError("Payment failed after 3 attempts")

Critical: generate the key once, before the first attempt, then reuse it across retries. If you generate a new key per retry, you've defeated the entire purpose.

Edge Cases Worth Handling

Concurrent requests with the same key — Two requests arrive simultaneously before either has stored a result. Use a Redis lock or database row-level lock during the "check and process" window.

Different payloads, same key — This is a client bug. Your server should detect it and return 422 Unprocessable Entity with a clear error message:

{"error": "Idempotency key already used with different request body"}

Key collisions — Vanishingly rare with UUID v4 (~5.3 × 10^36 possible values), but document that keys must be globally unique per endpoint, not just per session.

What Not to Use Idempotency Keys For

Idempotency keys are for non-idempotent operations — POST, DELETE (when results matter), and anything with side effects. You don't need them for GET or PUT (which are naturally idempotent when implemented correctly).

Also, idempotency keys don't replace request signing or authentication — they're a separate concern.

Wrapping Up

One UUID header, a Redis key, and a TTL: that's all it takes to make your payment flow, order creation, or notification dispatch safe to retry. Your users' fingers hover over "pay again" — idempotency keys make that safe.

If you're building or testing APIs and want to inspect exactly what's being sent, stored, and returned across retries, APIKumo lets you script request flows with variables and pre/post-processors — handy for verifying your idempotency implementation behaves correctly under retry conditions.

API Versioning Strategies: URL Path, Query Params, and Headers Compared

Mean — Wed, 03 Jun 2026 02:07:07 +0000

API Versioning Strategies: URL Path, Query Params, and Headers Compared

Every API evolves. Fields get renamed, endpoints get restructured, response shapes change. If you have clients depending on your API, breaking changes are a serious problem — and versioning is the mechanism that lets you ship those changes without burning everyone downstream.

The trouble is, there's no single "right" way to version an API. Three patterns dominate the industry, each with real trade-offs. Let's break them down with concrete examples so you can make an informed choice.

Strategy 1: URL Path Versioning

The most common approach embeds the version directly in the URL path:

GET /v1/users/42
GET /v2/users/42

Implementation (Express.js)

const express = require('express');
const app = express();

const v1Router = express.Router();
v1Router.get('/users/:id', (req, res) => {
  res.json({ id: req.params.id, name: 'Alice' }); // old shape
});

const v2Router = express.Router();
v2Router.get('/users/:id', (req, res) => {
  res.json({
    id: req.params.id,
    firstName: 'Alice',   // renamed in v2
    lastName: 'Smith',
    email: 'alice@example.com',
  });
});

app.use('/v1', v1Router);
app.use('/v2', v2Router);

Pros:

Immediately visible in browser, logs, and dashboards — no mystery about which version a request hit
Easy to route at the load balancer or CDN level
Simple to document and test

Cons:

Violates REST purists' view that a URL should identify a resource, not a version of a resource
Clients must update base URLs when upgrading
Can lead to copy-paste codebases if v2 is largely identical to v1

Strategy 2: Query Parameter Versioning

The version is passed as a query string parameter:

GET /users/42?version=1
GET /users/42?version=2

Implementation

app.get('/users/:id', (req, res) => {
  const version = parseInt(req.query.version) || 1;

  if (version >= 2) {
    return res.json({ id: req.params.id, firstName: 'Alice', lastName: 'Smith' });
  }
  return res.json({ id: req.params.id, name: 'Alice' });
});

Pros:

A single URL structure — easier to share and link
Optional parameter means you can default to latest (or earliest stable) without breaking callers that omit it

Cons:

Query params get lost in caches — proxy caches must be explicitly configured to vary on this parameter
Easy to forget or accidentally omit, silently calling the wrong version
Less idiomatic; most major APIs have moved away from this pattern

Strategy 3: Header-Based Versioning

The version is communicated via a custom request header:

GET /users/42
Accept-Version: 2

Or using the standard Accept header with a vendor media type:

GET /users/42
Accept: application/vnd.myapi.v2+json

Implementation

app.get('/users/:id', (req, res) => {
  const version = parseInt(req.headers['accept-version']) || 1;

  if (version >= 2) {
    return res.json({ id: req.params.id, firstName: 'Alice', lastName: 'Smith' });
  }
  return res.json({ id: req.params.id, name: 'Alice' });
});

Pros:

Clean URLs — the resource identifier is pure, version is metadata
Semantically correct from a REST standpoint
Works well with content negotiation for nuanced version control

Cons:

Headers are invisible in the browser address bar — harder to debug at a glance
Trickier to test with simple tools like curl or Postman without extra setup
Cache keys must include the header or you'll serve the wrong version from cache

Which Should You Choose?

Here's a practical rule of thumb:

Building a public API with many external consumers? Use URL path versioning. It's the most legible, easiest to document, and what most developers expect.
Internal API with controlled clients? Header versioning is clean and keeps URLs tidy.
Rapid prototype or small project? Query params are the quickest to implement, but plan to migrate if the API grows.

Regardless of strategy, be explicit about your deprecation policy. Set a sunset date, communicate it in a Sunset response header, and keep old versions alive long enough for clients to migrate:

Sunset: Sat, 31 Dec 2026 23:59:59 GMT
Deprecation: true
Link: <https://api.example.com/v2/users>; rel="successor-version"

Keeping All Versions in Sync Is the Real Work

The versioning strategy is the easy part. The hard part is maintaining documentation, test coverage, and client SDKs across multiple live versions simultaneously.

APIKumo is built for exactly this problem — it lets you manage multiple API versions in a single workspace, auto-generates client code in 26 languages per version, and keeps your docs in sync with your actual requests. When you eventually deprecate v1, you're not digging through a wiki to find what changed — it's all in the collection history.

If you're designing an API that needs to outlast its first iteration (most do), a clear versioning strategy from day one will save you weeks of migration pain later.