10 wichtige Komponenten der API-Dokumentation

Immer mehr Unternehmen nutzen die Leistungsfähigkeit von APIs, um ihr Geschäft zu optimieren. APIs sind zu einer Möglichkeit geworden, Mehrwert zu schaffen und einen zusätzlichen Service bereitzustellen.

Trotz ihrer allgemeinen Beliebtheit ist nicht jede API ein Erfolg. Die Einführung und Nutzung einer API bestimmen maßgeblich deren Erfolg. Um die Akzeptanz zu erhöhen, muss Ihre API leicht zu finden und zu verwenden sein.

Der beste Weg, dies zu erreichen, besteht darin, Ihre API detailliert zu dokumentieren. Dazu gehört die detaillierte Beschreibung wichtiger Komponenten, um sie leichter verständlich zu machen. Informieren Sie sich über einige der Komponenten, die Sie in Ihre API-Dokumentation aufnehmen sollten.

Was ist API-Dokumentation?

Bei der API-Dokumentation handelt es sich um technische Inhalte, die eine API detailliert beschreiben. Es handelt sich um ein Handbuch, das alle für die Arbeit mit der API erforderlichen Informationen enthält. Das Dokument behandelt den API-Lebenszyklus und Anweisungen zur Integration und Verwendung seiner Komponenten.

Die API-Dokumentation umfasst Ressourcenbeschreibungen, Endpunkte, Methoden, Anforderungen und Antwortbeispiele. Es kann auch praktische Anleitungen und Tutorials enthalten, die Benutzern zeigen, wie sie es integrieren. Durch die Erkundung der einzelnen Abschnitte erhalten Benutzer ein solides Verständnis für die Integration und Verwendung der API.

Editoren wie Google Docs wurden einst häufig für die professionelle API-Dokumentation verwendet. Heutzutage gibt es fortschrittlichere Tools wie Document 360, Confluence und GitHub Pages. Diese Tools helfen bei der Integration von Text und Code für einfachere Arbeitsabläufe.

1. Überblick und Zweck der API

Der erste Schritt bei der Dokumentation einer API besteht darin, den Benutzern mitzuteilen, worum es geht. Geben Sie Informationen über die Art der bereitgestellten Ressourcen an. APIs geben normalerweise verschiedene Ressourcen zurück, sodass der Benutzer anfordern kann, was er benötigt.

Die Beschreibung ist kurz und umfasst in der Regel ein bis drei Sätze, die die Ressource beschreiben. Beschreiben Sie die verfügbare Ressource, die Endpunkte und die mit jedem Endpunkt verbundenen Methoden. Als API-Entwickler beschreiben Sie am besten die Komponenten, die Funktionalität und den Anwendungsfall.

Hier ist ein Beispiel für eine Beschreibung der Airbnb-API:

2. Authentifizierungs- und Autorisierungsmethoden

APIs verarbeiten Tausende von Anfragen und enorme Datenmengen. Die Authentifizierung ist eine der Möglichkeiten, um sicherzustellen, dass die Daten Ihrer API und Benutzer vor Hackern geschützt sind. Die API-Authentifizierung überprüft die Identität eines Benutzers und gibt ihnen Zugang zu Ressourcen.

Es gibt mehrere Möglichkeiten, dies sicherzustellen Endpunktsicherheit. Die meisten APIs verwenden einen API-Schlüssel. Hierbei handelt es sich um eine Zeichenfolge, die ein Benutzer auf der Website generieren und zur Authentifizierung verwenden kann.

Die API-Dokumentation sollte Benutzer bei der Authentifizierung und Autorisierung ihrer Identitäten unterstützen. Das folgende Diagramm zeigt die Authentifizierungsinformationen der Twitter-API.

3. Endpunkte, URI-Muster und HTTP-Methoden

In diesem Abschnitt wird gezeigt, wie Sie auf die Ressource zugreifen. Die Endpunkte zeigen nur das Ende des Pfades an, daher ihr Name. Sie zeigen den Zugriff auf die Ressource und HTTP-Methoden Der Endpunkt interagiert mit, nämlich GET, POST oder DELETE.

Eine Ressource verfügt wahrscheinlich über mehrere Endpunkte. Jeder mit einem anderen Weg und einer anderen Methode. Endpunkte verfügen normalerweise über eine kurze Beschreibung ihres Zwecks und ein URL-Muster.

Das folgende Codebeispiel zeigt einen GET-Benutzerendpunkt auf Instagram.

Fang mich? Felder={Felder}&access_token={Zugriffstoken}

4. Anfrage- und Antwortformate

Sie müssen die Anfrage- und Antwortformate dokumentieren, damit der Benutzer weiß, was ihn erwartet. Die Anfrage ist eine URL eines Clients, der nach einer Ressource fragt, während die Antwort eine Rückmeldung vom Server ist.

Im Folgenden finden Sie eine Beispielanfrage, die Sie an die LinkedIn-API senden können.

ERHALTEN https://api.linkedin.com/v2/{service}/1234

Und hier ist eine Beispielantwort, die zurückgegeben werden kann:

{
 „id“: 1234,
 „relatedEntity“: „urn: li: relatedEntity: 6789“
}

5. Parameter und Header

Sie sollten auch die Parameter Ihrer Endpunkte dokumentieren, bei denen es sich um Optionen handelt, die Sie ihnen übergeben können. Parameter können eine ID oder eine Zahl sein, die die Menge oder Art der als Antwort zurückgegebenen Daten angibt.

Es gibt verschiedene Arten von Parametern, darunter Header-, Pfad- und Abfragezeichenfolgenparameter. Die Endpunkte können verschiedene Arten von Parametern enthalten.

Sie können einige Parameter als HTTP-Anforderungsheader einfügen. Normalerweise dienen diese wie ein API-Schlüssel Authentifizierungszwecken. Hier ist ein Beispiel für einen Header mit API-Schlüsseln:

Überschriften: {
 'X-RapidAPI-Key': 'fd40ada866msh4d8b69e4aa2dd19p12e47fjsn7efdcbc75635',
 'X-RapidAPI-Host': 'wft-geo-db.p.rapidapi.com'
}

Sie fügen Pfadparameter in den Textkörper des Endpunkts direkt in der URL ein. Sie zeigen einem Benutzer, wie und wo die Parameter platziert werden müssen und wie die Antwort aussehen wird. Die Wörter in geschweiften Klammern sind Parameter.

Sie können zur Darstellung von Pfadparametern auch Doppelpunkte oder eine andere Syntax verwenden.

/service/myresource/user/{user}/bicycles/{bicycleId}

Bei Abfrageparametern müssen Sie vor der Abfrage auf einem Endpunkt ein Fragezeichen (?) platzieren. Trennen Sie die einzelnen Parameter danach durch ein kaufmännisches Und-Zeichen (&). Microsoft verfügt über eine gute Dokumentation zur Graph-API.

6. Fehlercodes und Fehlerbehandlung

Manchmal schlagen HTTP-Anfragen fehl, was einen Benutzer verwirren kann. Fügen Sie erwartete Fehlercodes in die Dokumentation ein, um Benutzern das Verständnis der Fehler zu erleichtern.

LinkedIn stellt Standard-HTTP-Fehlercodes zur Fehlerbehandlung bereit:

7. Beispielcode-Snippets

Codefragmente sind wesentliche Bestandteile Ihrer Dokumentation. Sie zeigen Benutzern, wie sie die API in verschiedene Sprachen und Formate integrieren können. Geben Sie in der Dokumentation an, wie SDKs (Software Development Kits) in verschiedenen Sprachen installiert und integriert werden.

RapidAPI bietet gute Beispiele für Code-Snippets für Entwickler:

9. API-Versionierung und Änderungsprotokolle

Die API-Versionierung ist ein wesentlicher Bestandteil der API-Design. Es gewährleistet die unterbrechungsfreie Bereitstellung von Diensten für Ihre Benutzer. Durch die Versionierung kann die API mit neuen Versionen erweitert werden, ohne dass sich dies auf Clientanwendungen auswirkt.

Benutzer können ältere Versionen weiterhin verwenden oder rechtzeitig auf erweiterte Versionen migrieren. Wenn es neue Änderungen an den Protokollen gibt, nehmen Sie diese in die Dokumentation auf, damit die Benutzer davon Kenntnis haben.

Die Microsoft Graph-API verfügt über gut dokumentierte Änderungsprotokolle:

Fügen Sie abschließend wichtige Kontakte in die Dokumentation ein, um Unterstützung und Feedback zu erhalten. Dadurch wird sichergestellt, dass Benutzer Sie mit Fehlerberichten und Informationen zur Verbesserung der API erreichen können.

Der Wert der API-Dokumentation

Wenn Sie eine API mit kommerziellem Wert erstellen, bestimmt der Verbrauch ihren Erfolg. Und damit Benutzer Ihre API nutzen können, müssen sie sie verstehen.

Die Dokumentation erweckt eine API zum Leben. Es erklärt die Komponenten ausführlich in einer einfachen Sprache, die den Benutzern ihren Wert und ihre Verwendung vermittelt. Benutzer werden Ihre API gerne nutzen, wenn sie über eine großartige Entwicklererfahrung verfügen.

Eine gute Dokumentation trägt außerdem dazu bei, die Wartung und Skalierung der API zu vereinfachen. Teams, die mit der API arbeiten, können die Dokumentation zur Verwaltung nutzen.