API-Dokumentationsvideos, die Entwickler wirklich ansehen

Eine geschriebene API-Referenz ist präzise, vollständig – und fast unmöglich als Einstiegspunkt. Wer auf eurer Endpunktliste landet, kennt die Bedeutung jedes Feldes und hat trotzdem keine Vorstellung davon, wie die ersten fünf Minuten mit dieser API aussehen.

Genau diese Lücke füllt ein kurzes Video. Kein Ersatz für die Referenz, sondern ihre Ergänzung. Drei Minuten mit einem echten Key, einem echten Request und einer echten Response beantworten die Frage, die die Referenz nicht beantworten kann: Funktioniert das so, wie ich denke?

So nehmt ihr solche Videos auf, dass sie nützlich bleiben.

Entscheidet, was ein Video verdient

Video ist teuer im Unterhalt. Setzt es dort ein, wo Text am schwächsten ist:

• Der erste erfolgreiche Call: Vom leeren Terminal bis zur 200er-Response. Das wertvollste Einzelvideo, das ihr drehen könnt
• Authentifizierungsflows: OAuth-Redirects, Token-Austausch und Refresh-Logik sind Abläufe. Für Abläufe ist Video gemacht
• Mehrstufige Workflows: Ressource anlegen, Status pollen, Ergebnis abholen. In der Referenz wirken das drei zusammenhanglose Endpunkte
• Webhooks und Callbacks: Zwei Systeme im Gespräch lassen sich in Prosa kaum beschreiben
• Typische Fehler: Ein Video über einen 401 und dessen Behebung verhindert mehr Support-Tickets als jeder Absatz dazu

Kein Video verdienen: einzelne Endpunkt-Parameter, Enum-Werte, Rate-Limit-Zahlen. Die gehören in Text, wo man sie suchen, kopieren und in Sekunden aktualisieren kann.

Richtet eine Aufnahme-Sandbox ein

Nehmt niemals mit einem echten Key gegen Produktion auf. Baut euch vorher eine eigene Umgebung.

• Ein Wegwerf-Sandbox-Konto mit Keys, die ihr direkt danach rotiert
• Realistische Daten einspielen: test_user_1 und "foo" lassen eine Demo unecht wirken. Plausible Namen, Beträge und Zeitstempel schaffen Vertrauen
• Kurzlebiges Key-Format wählen, falls eure API eines anbietet – dann ist ein versehentlich sichtbares Token harmlos
• Shell-Umgebung prüfen: env-Ausgaben und Shell-History haben mehr Credentials geleakt als jedes Code-Snippet
• Caches und Abhängigkeiten vorwärmen, damit ihr keine Installation aufnehmt
• Benachrichtigungen ausschalten – eine Slack-Vorschau im veröffentlichten Video ist ein echter Vorfall

Auch in der Sandbox gilt: Behandelt jedes Einzelbild als öffentlich. Irgendwer drückt Pause.

Wählt das richtige Aufnahme-Setup

API-Demos umfassen meist zwei bis drei Oberflächen: Terminal, Editor, einen API-Client wie Postman oder Insomnia, manchmal einen Browser für das Dashboard.

• Fensteraufnahme pro Oberfläche hält den Bildausschnitt eng und blendet den Desktop aus
• Wenn ihr wechseln müsst, ordnet die Fenster vorher nebeneinander an und nehmt einen Bereich auf, der beide abdeckt. Alt-Tabben vor laufender Aufnahme irritiert
• 30 fps genügen für textlastige Inhalte, und niedrigere Bildraten lassen mehr Bitrate für scharfe Zeichen
• In nativer Auflösung aufnehmen – nachträgliches Hochskalieren erzeugt die Unschärfe
• Schriftgrößen auf 18–24 pt in Terminal und Editor. Was auf dem Monitor absurd wirkt, passt im Videofenster

Baut jeden Clip gleich auf

Konsistenz macht aus einer Sammlung von Screencasts erst Dokumentation. Ein verlässlicher Vierschritt:

1. Ziel in einem Satz: „Wir legen einen Kunden an und belasten ihn.”
2. Authentifizierung zeigen: Auch wenn es nur ein Header ist. Man muss sehen, wo der Key hingehört
3. Request live bauen: Tippen oder einfügen und Feld für Feld erklären. Sagt, warum jeder Parameter da ist
4. Response vorlesen: Beim JSON anhalten. Auf das Feld zeigen, das für den nächsten Schritt zählt

Und dann den nächsten Schritt ankündigen: „Diese id brauchen wir für die Zahlung – darum geht es im nächsten Video.”

Macht JSON und Code lesbar

Hier scheitern die meisten API-Videos. Der Request klappt, die Response füllt den Bildschirm, und die Zuschauer sehen eine unlesbare Wand aus geschweiften Klammern.

• Alles pretty-printen: durch jq pipen oder die Formatierung im Client aktivieren
• Unwichtiges einklappen: Die meisten API-Clients können Abschnitte falten. Klappt die Metadaten ein, die niemanden interessieren
• Auf das Schlüsselfeld zoomen: Ein Zoom auf die zwei entscheidenden Zeilen bringt mehr als jede Erklärung. In Recorded fügt ihr den Zoom nachträglich im Editor hinzu – so bleibt die Aufnahme auf korrekte Calls fokussiert
• Text-Overlay für den Feldnamen, wenn der Wert zählt: Ein Label an subscription_status liest sich schneller, als man es aussprechen kann
• Wartezeiten kürzen: Latenz, Polling-Schleifen und Rebuilds sind tote Luft. Rausschneiden und die verstrichene Zeit kurz einblenden

Sprecht wie Kollegen, nicht wie eine Spezifikation

Die formale Beschreibung steht schon in der Referenz. Euer Voice-over sollte sagen, was die Docs nicht sagen können:

• „Diesen Header vergessen alle.”
• „Ja, das Feld ist Pflicht, auch wenn es optional aussieht.”
• „Ein 422 an dieser Stelle liegt fast immer am Datumsformat.”

Genau dieser Kommentar ist das eigentliche Produkt eines Doku-Videos. Schreibt euch drei, vier solcher Sätze vorher auf – beim konzentrierten Tippen vergisst man sie leicht.

Haltet Clips kurz und modular

Ein zwanzigminütiger „kompletter API-Rundgang” stirbt, sobald sich ein Endpunkt ändert. Zwei bis vier Minuten pro Aufgabe überleben deutlich länger und lassen sich neben genau den Referenzabschnitt einbetten, den sie erklären.

Modular heißt auch: nachdrehbar. Ändert sich die Payload-Struktur, nehmt ihr einen 90-Sekunden-Clip neu auf, statt ein langes Video drumherum zu operieren.

Plant ein, dass sich die API ändert

Video-Dokumentation altert schneller als Text. Rechnet von Anfang an damit:

• Versionsnummern nennen und einblenden, damit ein veraltetes Video sichtbar veraltet ist
• Vergängliche UI-Elemente meiden – ein Dashboard-Redesign lässt ein Video schneller altern als API-Änderungen
• Rohaufnahmen und Projektdateien behalten, nicht nur die Exporte, damit eine Überarbeitung kein Neudreh wird
• Dateien nach Endpunkt und Version benennen, damit ihr nach einem Release seht, was zu aktualisieren ist
• Bei jedem Major-Release durchgehen und alles neu aufnehmen, was nicht mehr stimmt

Ein kurzes, ehrliches Video vom letzten Quartal ist in Ordnung. Ein souveränes Video mit einem Endpunkt, den es nicht mehr gibt, kostet Vertrauen.

Veröffentlicht dort, wo die Frage entsteht

Das bestplatzierte API-Video ist direkt in die Referenzseite des Endpunkts eingebettet – nicht in einer separaten Videobibliothek, die niemand besucht. Ab zwei Minuten Kapitel oder Zeitmarken ergänzen, den vollständigen Code aus dem Video als kopierbaren Text unter den Player setzen und die erfolgreiche Response als kurzes GIF für die Quickstart-Seite exportieren.

Kurze Checkliste

• Sandbox-Konto mit Wegwerf-Keys
• Realistische Testdaten
• Benachrichtigungen aus, Shell-History geleert
• Schrift vergrößert, Fenster angeordnet
• Struktur: Ziel → Auth → Request → Response
• Formatiertes JSON, Zoom auf Schlüsselfelder
• Wartezeiten geschnitten
• Version im Bild genannt
• Neben dem passenden Referenzabschnitt eingebettet
• Kopierbarer Code neben dem Video

Die Referenz sagt Entwicklern, was möglich ist. Eine gute Aufnahme zeigt ihnen, dass es tatsächlich funktioniert – und genau das bringt sie meist zum ersten erfolgreichen Call.