The renamed field that breaks a quickstart in silence#
Every documentation video ages, but an API quickstart ages worse and hides it better. When a product's interface moves, the stale walkthrough looks wrong on sight: the cursor lands on a button that is not there, and a reviewer scrubbing the clip catches it. An API quickstart offers no such tell. The terminal still shows a plausible `curl`, the response pane still shows well-formed JSON, the narration still sounds sure of itself. Nothing in the frame looks broken. The clip is simply describing a call that now returns a different shape, or a field the API renamed two releases ago, and the only person who learns this is the developer who pastes the command and gets back a 400.
That is the trap: a video captures the result of a call, never the call's contract. The pillar on where video earns its place in docs argues that reference material stays text; the API quickstart is where that rule grows teeth, because here the gap between "looks fine" and "is fine" is at its widest.
An API call also ages on more axes than any other clip. A UI walkthrough really breaks on one visible surface, its layout. An HTTP call breaks on several, and most leave no mark on screen.
| What can change under an API video | Visible in the frame? | Who finds out |
|---|---|---|
| endpoint path or method | sometimes, in the request line | a careful reviewer |
| a renamed request or response field | no | the developer who runs it |
| response body shape or a field's type | rarely | the developer who parses it |
| status code or error envelope | no | only on the unhappy path |
| auth scheme or a required header | no | at the 401 |
| a newly required parameter | no | at the 400 |
| a deprecation with a sunset date | no | months later, all at once |
Six of those seven are silent. They also move fast: Stripe alone has published more than 2,300 versioned releases of its machine-readable API description, the latest tagged v2344 on 15 July 20262. No hand-recorded quickstart tracks a source changing at that cadence. The reprieve hides in the same fact. Because the description is machine-readable, a diff of it names exactly which fields moved, and that is the hook the rest of this piece hangs on.
What an API video should show, and what it must not#
The instinct that sinks these videos is the twenty-minute tour of the entire reference. It is the wrong unit twice: too long to finish, and built almost entirely from the lookup content that text serves better. A video earns a place in API docs for one job, the thing prose is worst at, which is conveying the shape of an interaction and how its parts relate. Twilio's Video SDK quickstart turns on three nouns that only mean anything together: a Room that is "the basic building block for a Programmable Video application," Participants "connected to a Room," and Tracks, "the media streams that are shared within a Room"3. A newcomer absorbs that nesting faster from thirty seconds of one call running than from three paragraphs of nouns.
| Put in the video | Keep in the text beside it | Why |
|---|---|---|
| the single call that produces the aha, start to finish | the full endpoint and field reference | reference is lookup, and must stay searchable and copyable |
| the shape of the response and the one field that matters | every field's type and constraint | a schema table beats a paused frame |
| how two objects relate: get a token, then connect; create, then poll | exhaustive parameter lists | relationships are what motion shows best |
| one real value flowing from request into response | secrets, live keys, account identifiers | never film a credential |
The honest benchmark is that the most admired API docs barely use video at all. Stripe's reference leads with copyable, runnable code samples rather than clips, precisely because reference is the part a reader scans, copies, and has to trust to the character. Video sits upstream of that, at the getting-started moment when a developer needs to watch one request succeed before any of the reference means much. Hold it to that call. How small to cut a doc clip is its own decision, but for an API the ceiling is low: one call, its response, done.
Making a call and its JSON readable on screen#
An API video crowds two of the least codec-friendly surfaces into one frame: a terminal and a wall of JSON. The legibility mechanics, editor font size, zoom, and the reason H.264 smears syntax highlighting first, are worked through for developer-education screencasts and carry over here without change. The API-specific problem is the response body. Pretty-printed JSON at a terminal's default size is unreadable in a 1080p embed and hopeless in a 640px docs column, so pipe it through a formatter, collapse the body to the few fields the narration actually names, and zoom to those. Show the `id` and the `status`, not forty lines of nested metadata no one will read at three pixels tall.
The second constraint is copyability. A viewer cannot select a `curl` command out of a video, because the codec turned it into pixels. So the copyable version has to live in the text next to the clip, which is also the version you can test. That is the reason the terminal half of an API video is better driven from a script than typed live, and the tradeoffs between asciinema, a raw screen recording, and tape-driven replay decide which route fits. Type nothing by hand that a reader will have to retype by eye.
The fixture a video and a contract test can share#
Here is the move that makes an API video maintainable rather than merely correct on the day you shot it: feed the video and your test suite from the same fixtures.
Begin at the source of truth. An OpenAPI description is "a standard, programming language-agnostic interface description for HTTP APIs," and its Example, Schema, and Response Objects pin down both the shape of a call and concrete sample values1. Those examples are not decoration. Two kinds of tooling already read them:
- A mock server. Prism turns "any OpenAPI2/3 and Postman Collection file into an API server with mocking," and can serve the spec's own `examples` as its responses4. Record the video against that mock and the JSON on screen is, by construction, the JSON in the docs, identical take after take, with no live account and no secret in the frame.
- A contract test. Dredd "takes your API description document, creates expectations based on requests and responses documented in the document, makes requests to tested API, checks whether API responses match the documented responses"5. Run it in CI and the day the implementation renames a field, the very example the video was built from turns the build red.
Bolt those together and the video inherits the test's coverage. The example fixture becomes one artifact feeding three consumers: the written docs render it, the contract test checks it against the live API, and the video is recorded against a mock that serves it. A renamed field can no longer break the video quietly, because it breaks the contract test loudly first, in the same pull request. Docs that test themselves is the general form of this discipline, and the video is one more output wired to the same tested example.
Rebuilding the clip on the commit that renamed the field#
Being accurate on shoot day is not the target. Staying accurate across the next hundred releases is, and that means the clip has to regenerate rather than get re-shot, on the same commit that changed the API, so the fix ships alongside the break.
The loop is short. A change lands that renames a field. The contract test fails, because the documented example no longer matches the response. Someone updates the example, the single edit that repairs the docs, the test, and the video's input at once. CI restarts the mock, re-records the clip against it, and republishes. Nobody opens a timeline; the diff that renamed the field is the diff that rebuilt the video. This is the regeneration model that keeps a whole tutorial library current, aimed at the fastest-rotting clip in the set.
Our own engine, aidemo, disclosed as ours, automates only the browser half of that loop, and its limits bite harder here than in most doc videos. Because it replays a version-controlled spec instead of a live capture, an embedded clip can rebuild itself on the release that moved the product. What it cannot do is see past a browser tab: the terminal and the `curl` that carry an API call sit entirely outside its frame, so you render those with a tape-based terminal tool and splice the two. The spec is authored by an agent and then revised as plain text, and nothing in the workflow resembles a drag-and-drop editor. That plumbing is not the argument. The argument is that an API video stays true only when its inputs are the same tested fixtures the rest of your docs already rebuild from, so a broken quickstart fails your CI instead of your reader.
Sources#
- OpenAPI Initiative — OpenAPI Specification (latest): a language-agnostic interface description for HTTP APIs, with Example, Schema and Response Objects
- stripe/openapi — Stripe's machine-readable OpenAPI specification, 2,300+ versioned releases covering v1 and v2 endpoints and events
- Twilio — Video Quickstart for JavaScript (Room, Participants, Tracks as the getting-started model)
- Stoplight Prism — turn any OpenAPI or Postman file into a mock and validation server
- Dredd — How It Works: validate that an API's responses still match the responses documented in its description
FAQ#
Should an API quickstart be a video or code samples?#
Both, doing different jobs. Use a short video for the one thing text struggles with: the shape of a first successful call and how its objects relate, the getting-started aha. Keep the reference itself, every endpoint, field, and type, in copyable code samples, because that is the part a developer scans, searches, and pastes exactly. The most admired API docs, Stripe's among them, lead their reference with runnable code, not clips, and reserve video for the conceptual on-ramp.
How do you keep an API documentation video in sync with the API?#
Build it from the same fixtures your tests use, not from a live hand-recorded session. Record against a mock server generated from your OpenAPI examples (Prism does this), and run a contract test such as Dredd that checks those same examples against the real API in CI. When a field is renamed, the contract test fails in the pull request, someone updates the shared example, and the clip re-records from it, so the video is fixed by the same commit that broke the API.
What should an API documentation video actually show?#
One call, from request to response, and the relationships a schema table cannot animate. Show the request line, a real value flowing into the response, and the one or two fields the narration names, formatted and zoomed so they survive compression. Leave the exhaustive field reference, error catalogs, and every parameter in the text beside it. Never put a real secret or live key on screen, and never let the clip grow into a twenty-minute tour of the whole API.
