Entwicklung

API-Dokumentation-Vorlage in Markdown

Gute API-Dokumentation lässt Entwicklerinnen und Entwickler in wenigen Minuten die erste erfolgreiche Anfrage stellen. Diese Vorlage legt einen Endpunkt von Anfang bis Ende dar, damit du das Muster für die übrigen übernehmen kannst: Überblick, Authentifizierung, Parameter, ein Beispielrequest, Antwortfelder, Fehler und ein Kontakt für Support.

Diese Vorlage im Editor öffnen

Kategorie: Entwicklung
Standardstil: Technisch

Wann du sie brauchst

Greif darauf zurück, wenn ein Partner, eine Kundin oder ein internes Team eine Referenz braucht, die offline lesbar ist, einem Vertrag beiliegt oder mit einem Release aufbewahrt wird. Deine Leserschaft besteht aus Entwicklerinnen und Entwicklern, die von der Seite kopieren, deshalb bleibt der Text im PDF markierbar und die Codebeispiele behalten ihre Formatierung.

Was enthalten ist

Überblick und Authentifizierung mit Ausfüllfeldern für Projekt, Betreuerin, Datum und Support-E-Mail.
Ein Endpunkteintrag mit einer Parametertabelle für Typ, Pflichtangabe und Beschreibung, plus einem curl-Beispiel.
Eine Tabelle für Antwortfelder und eine Fehlertabelle mit Status, Bedeutung und der zu ergreifenden Maßnahme.

Tipps für ein besseres Dokument

Verwende in jedem Beispiel Platzhalter-Token statt eines echten Schlüssels. Kennzeichne die Sprache in jedem Codeblock, damit MDPress die Syntaxhervorhebung anwenden kann.
Sobald du mehr als ein paar Endpunkte dokumentierst, schalte das Inhaltsverzeichnis mit Seitenzahlen ein, damit Leserinnen direkt zum gesuchten Punkt springen können.

Vorlagenvorschau

Projekt oder Thema API-Referenz

Verantwortlich: Dein Name · Aktualisiert: Datum

Überblick

Erkläre Zweck, Basis-URL und Version der API.

Authentifizierung

Beschreibe, wie man ein Token erhält und sicher überträgt. Verwende in Beispielen Platzhalter.

Ressourcen auflisten

GET /v1/resources

Parameter	Typ	Erforderlich	Beschreibung
limit	integer	Nein	Maximale Ergebnisse pro Seite
cursor	string	Nein	Von der vorherigen Anfrage zurückgegebener Cursor

Beispielanfrage

curl https://api.example.com/v1/resources

Antwortfelder

Feld	Typ	Beschreibung
data	array	Zurückgegebene Ressourcen
next_cursor	string oder null	Token für die nächste Seite

Fehler

Status	Bedeutung	Aktion
400	Ungültige Eingabe	Parameter überprüfen
401	Authentifizierung erforderlich	Zugangsdaten prüfen
429	Ratenlimit erreicht	Hinweise zum erneuten Versuch beachten

Support

E-Mail

Ausfüllfelder wie dein Name und das Datum werden ersetzt, sobald du die Vorlage im Editor öffnest.