So schreiben Sie eine API-Übersicht, die Entwickler nutzen können
Private Beta. Der Zugang läuft über die Warteliste, und die kostenpflichtigen Tarife starten, wenn die Beta endet. Tragen Sie sich auf die Warteliste ein.
Eine API-Übersicht ist die erste Seite, die ein Entwickler liest, und oft die einzige, bevor er entscheidet, ob er die API anbindet. Sie sollte einige Fragen schnell beantworten und immer an derselben Stelle stehen, mit denselben Überschriften.
Was hineingehört, der Reihe nach
- Zusammenfassung. Was die API tut, für wen sie gedacht ist und ein typischer Anwendungsfall, in zwei oder drei Sätzen.
- Basis-URL. Eine Zeile mit der Version im Pfad, dazu die Sandbox-URL, falls es eine gibt.
- Authentifizierung. Wie man einen Schlüssel erhält, welcher Header ihn trägt und ob sich die Schlüssel je Umgebung unterscheiden.
- Endpunkte. Eine Tabelle mit Methode, Pfad, einer einzeiligen Beschreibung und der Angabe, ob ein Endpunkt seitenweise ausgeliefert wird und ob er idempotent ist. Die vollständigen Parameterdetails können in der Referenz stehen.
- Ratenbegrenzung. Das Limit als Zahl, die Header, die es melden, und was ein Client tun sollte, wenn es überschritten wird.
- Versionierung. Was als inkompatible Änderung gilt und wie viele Tage Vorlauf eine abgekündigte Version erhält.
- Fehler. Eine Tabelle mit Statuscodes, Fehlercodes, Bedeutungen und der Angabe, ob sich jeder einzelne sicher wiederholen lässt.
Fehler, die Entwickler Zeit kosten
- Die Authentifizierung auf einer eigenen Seite verstecken, sodass der erste Aufruf an einem Link hängt, den der Leser erst finden muss.
- Endpunkte auflisten, ohne zu sagen, welche Listen seitenweise ausgeliefert werden oder welche Schreibvorgänge idempotent sind, sodass ein Wiederholungsversuch einen doppelten Datensatz anlegen kann.
- Nur den Erfolgsfall dokumentieren, ohne Fehlertabelle, sodass jeder Client seine eigene Behandlung erfindet.
- Ratenbegrenzungen als "angemessen" oder "faire Nutzung" angeben statt als Zahl und Headername.
- Nichts über Abkündigungen sagen, sodass eine abgeschaltete Version ohne Vorwarnung nicht mehr funktioniert.
- Das Layout von einer API zur nächsten abdriften lassen, sodass Entwickler die Seite jedes Mal neu lernen müssen, wenn sie eine neue öffnen.
Ein vollständiges Beispiel: Parcel Tracking API
Dies ist ein fiktives Beispiel. Die Parcel Tracking API, ihre Schlüssel, IDs, Grenzwerte und Fehlercodes sind alle erfunden, stimmen aber miteinander überein, sodass Sie jeden Abschnitt mit den anderen abgleichen können.
Zusammenfassung. Mit der Parcel Tracking API kann ein Händler eine Sendung anlegen, ihren aktuellen Status abrufen und die Tracking-Ereignisse jedes Pakets auflisten. Sie richtet sich an Entwickler, die einen Onlineshop oder ein Lagersystem mit Versandlabels und Zustellmeldungen verbinden.
Basis-URL. https://api.parceltrack.example/v2 für die Produktion. Die Sandbox ist https://sandbox.parceltrack.example/v2 und akzeptiert nur Testschlüssel.
Authentifizierung. Senden Sie Ihren API-Schlüssel als Bearer-Token im Authorization-Header: Authorization: Bearer pt_live_.... Schlüssel, die mit pt_live_ beginnen, funktionieren nur auf der Basis-URL der Produktion, und Schlüssel, die mit pt_test_ beginnen, nur auf der Sandbox. Legen Sie Schlüssel unter Einstellungen und dann unter API-Schlüssel an. Ein widerrufener Schlüssel liefert bei der nächsten Anfrage 401.
Endpunkte. Jeder Pfad unten ist relativ zur Basis-URL.
| Methode | Pfad | Beschreibung | Seitenweise | Idempotent |
|---|---|---|---|---|
| POST | /shipments | Eine Sendung anlegen und ihre Sendungsnummer erhalten. | nein | nur mit einem Idempotency-Key-Header |
| GET | /shipments/{id} | Eine Sendung und ihren aktuellen Status abrufen. | nein | ja |
| GET | /shipments | Die Sendungen Ihres Kontos auflisten, neueste zuerst. | ja | ja |
| GET | /shipments/{id}/events | Die Tracking-Ereignisse einer Sendung auflisten, neueste zuerst. | ja | ja |
| POST | /shipments/{id}/cancel | Eine Sendung stornieren, die noch nicht abgeholt wurde. | nein | nein |
POST /shipments ist nur dann idempotent, wenn Sie einen Idempotency-Key-Header senden. Die API behält diesen Schlüssel 24 Stunden lang, und ein Wiederholungsversuch mit demselben Schlüssel liefert die ursprüngliche Sendung zurück, statt eine zweite anzulegen. Seitenweise ausgelieferte Endpunkte akzeptieren limit (1 bis 100, Standard 25) und cursor und geben next_cursor zurück, der auf der letzten Seite null ist. Wenn Sie eine Sendung zweimal stornieren, kommt 409 zurück. Prüfen Sie deshalb den Status, bevor Sie eine Stornierung wiederholen.
Ratenbegrenzung. Die Produktion erlaubt 300 Anfragen pro Minute und API-Schlüssel. Die Sandbox erlaubt 60 Anfragen pro Minute und Schlüssel. Jede Antwort enthält drei Header: RateLimit-Limit (das Kontingent für das Zeitfenster), RateLimit-Remaining (die im aktuellen Zeitfenster verbleibenden Anfragen) und RateLimit-Reset (Sekunden bis zum Zurücksetzen des Zeitfensters). Abgewiesene Anfragen zählen mit.
Überschreitet ein Schlüssel sein Kontingent, liefert die API 429 mit einem Retry-After-Header, der angibt, wie viele Sekunden Sie warten sollen. Warten Sie mindestens so lange und wiederholen Sie dann die Anfrage. Liefern Anfragen weiterhin 429, verlängern Sie die Wartezeit exponentiell, beginnend mit 1 Sekunde, verdoppeln sie bei jedem Versuch, fügen eine zufällige Streuung hinzu und brechen nach 5 Versuchen ab. Wiederholen Sie nicht in einer engen Schleife.
Versionierung und Abkündigung. Die aktuelle Version ist v2 und steht im Pfad der Basis-URL. Eine inkompatible Änderung ist eine, die einen funktionierenden Client brechen kann: das Entfernen oder Umbenennen eines Feldes, die Änderung des Feldtyps, eine Änderung der Bedeutung eines Fehlercodes oder ein optionaler Parameter, der verpflichtend wird. Neue Endpunkte, optionale Parameter und Antwortfelder sind nicht inkompatibel, daher müssen Clients Antwortfelder ignorieren, die sie nicht kennen. Eine abgekündigte Version liefert einen Deprecation-Header und einen Sunset-Header mit dem Abschaltdatum. Die Vorlaufzeit beträgt mindestens 180 Tage vor dem Sunset-Datum, und der Kontoinhaber erhält eine E-Mail, sobald die Ankündigung beginnt.
Fehler. Jeder Fehler liefert einen JSON-Body mit einem error-Code aus der Tabelle unten und einer message für die Logs. Werten Sie den Code aus, nicht den Text der Meldung.
| Status | Fehlercode | Bedeutung | Sicher wiederholbar |
|---|---|---|---|
| 400 | invalid_request | Ein Feld fehlt oder hat das falsche Format. Der Body listet jedes Problem unter details auf. | nein |
| 401 | unauthorized | Der Schlüssel fehlt, ist widerrufen oder ist für die andere Umgebung bestimmt. | nein |
| 404 | shipment_not_found | Unter dieser ID gibt es in Ihrem Konto keine Sendung. | nein |
| 409 | shipment_state_conflict | Die Aktion passt nicht zum Status der Sendung, zum Beispiel das Stornieren einer Sendung, die bereits abgeholt wurde. | nein |
| 429 | rate_limited | Der Schlüssel hat das Kontingent für die laufende Minute ausgeschöpft. | ja, nach der Wartezeit aus Retry-After |
| 503 | service_unavailable | Vorübergehende Störung. Wiederholen Sie mit verlängerter Wartezeit und verwenden Sie bei POST-Anfragen denselben Idempotency-Key erneut. | ja, mit verlängerter Wartezeit |
Schwache und starke Sätze
Drei typische Sätze aus Übersichten, jeweils gefolgt von einer stärkeren Umformulierung desselben Punkts.
Schwach: "Die Authentifizierung nutzt Tokens."
Stark: "Senden Sie Ihren API-Schlüssel im Authorization-Header als Bearer, gefolgt vom Schlüssel. Schlüssel, die mit pt_test_ beginnen, funktionieren nur in der Sandbox, und Schlüssel, die mit pt_live_ beginnen, nur in der Produktion."
Schwach: "Ratenbegrenzungen gelten für alle Endpunkte."
Stark: "Jeder Schlüssel darf an die Produktion 300 Anfragen pro Minute senden und an die Sandbox 60. Lesen Sie RateLimit-Remaining aus jeder Antwort. Wenn Sie ein 429 erhalten, warten Sie die Anzahl Sekunden aus Retry-After, bevor Sie die nächste Anfrage senden."
Schwach: "Listen werden seitenweise ausgeliefert."
Stark: "Listen-Endpunkte liefern standardmäßig 25 Einträge und bis zu 100, wenn Sie limit übergeben. Übergeben Sie den Wert next_cursor aus jeder Antwort als cursor, um die nächste Seite zu erhalten. Ist next_cursor null, haben Sie die letzte Seite erreicht."
Prüfliste
Eine prüfende Person kann diese acht Fragen in etwa fünf Minuten durchgehen.
- Kann ein Entwickler mit nur dieser Seite einen ersten erfolgreichen Aufruf machen?
- Enthält die Basis-URL die Version, und gibt es eine Sandbox-URL?
- Nennt der Abschnitt zur Authentifizierung den Header, das Schlüsselformat und die Umgebung, in der jeder Schlüssel funktioniert?
- Gibt jeder Endpunkt an, ob er seitenweise ausgeliefert wird und ob er idempotent ist?
- Sind Ratenbegrenzungen als Zahlen angegeben, mit den Headernamen und dem Verhalten bei 429?
- Definiert der Abschnitt zur Versionierung eine inkompatible Änderung und nennt er die Vorlaufzeit vor der Abschaltung?
- Sagt jede Zeile der Fehlertabelle, ob ein Wiederholungsversuch sicher ist, und stimmt diese Angabe mit der Endpunkttabelle überein?
- Stimmen Zahlen, IDs und Codes in allen Abschnitten überein?
Übersichten konsistent halten
Wenn Sie mehrere APIs pflegen oder sie für mehrere Kunden schreiben, hält eine feste Vorlage Reihenfolge und Tabellen gleich. Wordspecs hat eine Vorlage für API-Übersichten mit diesen Feldern, und die Beispiel-API-Übersicht (ein fiktiver Paketverfolgungsdienst) zeigt, wie sie aussieht. Blätter lassen sich als Markdown, PDF und Word exportieren.
Dazu passend: Export als Markdown, PDF und Word.