An API video can explain a complete task by following one request into the application that uses its response. The viewer needs to recognize the input, understand the returned values, and see what their own code would do with them. A diagram helps when the relationship between those steps is difficult to see in terminal output.
The example below uses Slotbook, a fictional scheduling API. A developer submits a room and a start time, receives a booking identifier, and displays the reservation in a calendar. Its endpoint and payload are teaching fixtures, not instructions for an existing service.
The recording needs a reproducible request
A producer needs access to a test environment and a request that someone has already run successfully. The source package includes the API version, authentication prerequisites, request body, and response. An application screenshot establishes where the response goes. A failed request needs its own captured output if the video covers error handling.
For Slotbook, the demonstration contract defines these fields:
POST /v1/bookings
Content-Type: application/json
Authorization: Bearer DEMO_TOKEN
{
"room_id": "room_04",
"starts_at": "2026-10-06T10:00:00Z",
"duration_minutes": 30
}
The fictional success response supplies the identifier the application stores:
{
"booking_id": "booking_117",
"room_id": "room_04",
"starts_at": "2026-10-06T10:00:00Z",
"duration_minutes": 30,
"status": "confirmed"
}
The final calendar card reads “Room 04, 10:00–10:30 UTC” and links to booking_117. Using UTC throughout avoids an unexplained conversion between the payload and the calendar. If the real product displays local time, the example needs an explicit timezone label and the correct conversion.
In a production video, the actual API contract replaces this fixture. The producer checks field names against the retained request instead of inventing fields that make the animation simpler. Credentials stay out of public footage; a visible placeholder must clearly identify itself as a placeholder.
Build the visual sequence around the same reservation
The storyboard follows the room and time through the request, response, and calendar. Keeping those values consistent lets the viewer connect the API call to the result without learning a new example in each scene.
- Show the application's missing reservation. The calendar displays Room 04 with the selected slot empty. A small request panel names the room and start time. This establishes the task before the endpoint appears.
- Reveal the request fields that define the booking. The method and path remain visible while the emphasis moves from
room_idto the time fields. The authentication prerequisite belongs in the accompanying text unless authentication is the lesson. - Show the response arriving after submission. The response panel introduces
booking_idandstatus. Unrelated headers stay in the downloadable example, where a reader can inspect them without pausing the video. - Show the application using the response. The calendar gains a card with the same room and time. A matching identifier connects the card to the response, so the scene explains more than a successful HTTP exchange.
A diagram should distinguish the API service from the application that calls it. If the client renders the calendar, the animation must not imply that the API directly edits the interface. Internal components require documentation or another verified source; an undocumented availability checker would be an invented architecture.
The clip demonstrates one way to indicate a transfer. It does not prescribe a literal picture of network traffic. A request card moving between labeled surfaces can also work if its location and meaning remain clear.
A second request needs a different result
The Slotbook fixture defines an occupied slot as a conflict. A second call with the same room and time returns slot_unavailable; the calendar retains its existing booking. The error scene compares the changed response with the successful response and shows the application's next action, such as asking the user to select another slot.
A real API may handle duplicates, conflicts, or retries differently. The video must follow the documented behavior of that API. An attractive recovery animation cannot establish an idempotency guarantee, and one successful retry cannot prove that every repeated request is safe.
The storyboard records what changes between runs. For this comparison, only the slot's availability changes; the room, duration, and application layout stay constant. That constraint makes the reason for the different result visible.
Code needs reading time and a written companion
The viewer must be able to distinguish field names and compare values at the size of the embedded player. A full editor window often contains too much unrelated text, so a close crop can show the relevant request and retain a small filename or endpoint label for context.
Narration explains why the application needs the booking identifier while the screen shows its spelling. A pronunciation of every slash and underscore would consume the time the viewer needs to read. A tutorial may still need to name an exact command or error code when that name helps the learner find it.
The written companion contains the complete request, expected response, prerequisites, and API version. It also states whether the video removes waiting time. A learner should not have to reconstruct copyable code from frames.
Review the result against the API contract
A technical reviewer compares each displayed value with the retained example, checks the order of events, and follows the written instructions in the test environment. The finished video shows a booking request, its confirmed identifier, and the calendar reservation that uses it. If it includes the conflict example, the same reviewer verifies that the error leaves the existing reservation unchanged.
The product truth prompt records those sources. A broader lesson that also covers a CLI or SDK belongs with the developer-tool guide.