API-Dokumentation: So schreibt man sie & Beispiele

Was ist API-Dokumentation?

API-Dokumentation ist eine Anleitung, die Entwicklern und anderen interessierten Personen erklärt, wie sie Ihre API und ihre Dienste für einen bestimmten Zweck benutzt. Es enthält in der Regel Code-Muster, Tutorials und Details zu den Funktionen, Klassen und Rückgabetypen. Es bietet den Entwicklern im Wesentlichen alle Informationen, die sie benötigen , um Integrationen mit der API zu erstellen und API-Aufrufe mit der Software durchzuführen.

API-Aufrufe sind eine Art von Anfrage, die vom Drittanbieter-Entwickler an die API der Plattform gestellt wird. Die API Aufrufe werden in der Dokumentation beschrieben und sagt dem Entwickler genau, was er von der API verlangen kann und wie.

API-Dokumentation erklärt ihre Endpunkte, interpretiert, warum Sie sie verwenden möchten, und gibt sehr viele spezifische Beispiele dafür, wie Sie sie verwenden könnten.

APIs sind wichtig, weil es bedeutet, dass Entwickler nicht immer wieder dieselben Softwarelösungen von Grund auf erstellen müssen. APIs bedeuten, dass Entwickler von anderen Plattformen profitieren können, die bereits erstellt worden sind und ihre Funktionalität in ihre eigenen Programme schon integriert haben. Viele große Plattformen haben APIs, einschließlich Twitter und GitHub.

API-Typen

Für das Team

Sie können eine API haben, die nur für Ihr Unternehmen intern ist und daher nur von Mitgliedern verwendet werden sollen. Ziel dieser Art von API wäre es, die Übertragung von Daten zwischen Teams zu rationalisieren, also sind die internen Entwickler Ihres Unternehmens diejenigen, die für die Verwendung dieser API verantwortlich sind.

Für die Partner

Partner-APIs werden außerhalb der Organisation geteilt, aber nur mit denen, die eine Geschäftsbeziehung mit der Firma haben, die die API bereitstellt. Nur autorisierte Clients haben Zugriff auf die API und infolgedessen sind Sicherheitsmaßnahmen bei dieser Art von API tendenziell strenger.

Für die Endbenutzer

Es sind APIs für Endbenutzer oder offene APIs können von jeder Entwickler ohne Einschränkungen. Diese APIs haben keine besonders strenge Authentifizierung und Autorisierungsmaßnahmen, weil die Anbieter wollen, dass die API von so vielen Entwicklern angenommen wird wie möglich. Manchmal wird diese Art von API für eine Abonnementgebühr zur Verfügung stehen, die entsprechend der Anzahl von durchgeführten API-Aufrufen gestuft werden.

Wer schreibt API-Dokumentationen?

Da Entwickler natürlich diejenigen sind, die die APIs bauen, werden sie oft mit dem Schreiben von APIs Dokumentation beauftragt. Leider kann die von Entwicklern getriebene Dokumentation oft zu technisch sein, weil Entwickler so nah an dem Thema sind. Die Dokumentation von Entwicklern kann auch auf der Strecke bleiben, weil sich Entwickler eigentlich auf den Aufbau und die Wartung der API konzentrieren.

Aus diesem Grund beschäftigen viele Unternehmen professionelle technische Redakteure zur Erstellung ihrer API-Dokumentation. Technische Autoren haben die technische Fähigkeit, die API zu verstehenund die kreativen Fähigkeiten, interessante Inhalte für diejenigen Endbenutzer zu schreiben, die Entwickler sind.

Die API-Entwickler verschaffen dem technischen Autor die Informationen, die er benötigt, um die API genau dokumentieren zu können. Falls Teile in der Dokumentation fehlen, können die Entwickler dem technischen Autor helfen, sie einfüllen – mit dem Endergebnis, dass Sie ein Dokument haben, das für seine Zielgruppe klar und zugänglich ist,

Schauen Sie sich auch unseren Artikel an, wie man ein bezauberndes API-Entwickler-Erlebnis mit der Dokumentation erstellt.

Vorteile der API-Dokumentation

Für Anbieter, die eine API anbieten wollen, kann die Erstellung von Dokumentation viele wichtige Vorteile für ihre Organisation haben.

Verbessert die Entwicklererfahrung der API

Zuallererst verbessert die API-Dokumentation die Entwicklererfahrung. Es spielt keine Rolle, wie gut Ihre API ist, wenn potenzielle Entwickler nicht verstehen, wie sie es verwenden sollen. Gute API-Dokumentation hilft Entwicklern, die verschiedenen angebotenen Endpunkte sowie Beispiele für spezielle Anwendungsfälle zu verstehen,. Wenn Sie die Entwicklungserfahrung verbessern, erhöhen Sie die Anzahl der potentiellen Nutzer, die Sie für Ihr Produkt gewinnen können.

Reduziert die Zeit für den Einstieg interner Entwickler oder externre Partner

Gute API-Dokumentation bedeutet, dass Ihre Support- und Erfolgsteams weniger Zeit damit verbringen müssen, neue interne Funktionen, Entwickler oder externe Partner einzuführen. Neue Benutzer Ihrer API haben alle Informationen, die sie benötigen, um mit Ihrer Plattform loszulegen und sich für den Erfolg einzusetzen. Wenn die Prozesse dokumentiert sind, müssen bestimmte Teammitglieder nicht mehr eingreifen.

Effiziente Produktpflege und schnellere Updates

Wenn Sie Ihre API effektiv dokumentieren, bedeutet dies, dass Sie die Wartung Ihres Produkts verwalten und häufiger und schneller aktualisieren können. Mit API-Dokumentation wissen Sie genau, was Ihr Produkt zu tun hat und wie es Endanwender helfen soll. Die Dokumentation gibt Ihnen eine intimere Ansicht der API und ermöglicht es Ihnen, Aktualisierungen schneller einzuführen, die dann von Benutzern übernommen werden.

Unterstützt sowohl interne als auch externe Benutzer beim Verstehen der API und ihrer Fähigkeiten

Einer der Hauptvorteile der API Dokumentation ist, dass es sowohl internen als auch externen Benutzern hilft, die API zu verstehen – wie sie es verwenden können, und wie sie die API für ihre eigenen Zwecke einsetzen können. Wenn Sie die potentiellen Fähigkeiten der API nicht erklären, dann werden neue Benutzer nicht wissen, wie sie sie verwenden und Sie werden eine langsame Produkteinführung erleben. Potenzielle Benutzer einer API verwenden die Dokumentation als einen Weg, um die Entscheidung zu treffen, ob Sie Ihr Produkt nutzen.

Die Go-to-Quelle für Teammitglieder, die sich an API-Ziele orientieren

Interne Teammitglieder in Ihrer Organisation können sich auf die API-Dokumentation beziehen, wenn sie sich selbst mit den Zielen Ihrer API vertraut machen möchten. Selbst diejenigen, die nicht direkt am Aufbau der API oder am Schreiben der Dokumentation beteiligt waren. werden den beabsichtigten Zweck der API verstehen und die Arbeit von dem API Entwicklungsteam unterstützen.

Ermöglicht die schnelle Identifizierung von Fehlern und Problemen

Wenn Sie die API dokumentieren, können Sie durch das Testen der API Fehler und Probleme schnell identifizieren, um alle seinen Funktionen zu dokumentieren. Wenn Ihre API nicht wie geplant funktioniert, kann dieses Feedback an das Entwicklungsteam des API weitergegeben werden. Das Team kann dann Schritte zur Problembehebung ergreifen. Das Ergebnis ist eineprofessionelle und effektive API, die wie erwartet funktioniert.

Die Struktur der API-Dokumentation – Design und Funktion

Ein Abriss

Die Abrisse Ihrer API-Dokumentation werden auch als Übersicht bezeichnet. Es enthält eine Zusammenfassung der API und ihrem Zweck, und kann potenzielle Benutzer über die Vorteile informieren, die die Nutzung dieser API gegenüber anderen hat.

Anleitungen

Tutorials bilden den Hauptteil der API und ihr Zweck ist es, den Benutzern das Konzept der API beizubringen und wie sie es wirksam verwenden. Es enthält in der Regel Schritt-für-Schritt Anleitungen, wie man die API integriert und wie richtige Funktionstüchtigkeit aussieht.

Authentifizierung

Authentifizierung ist, wie der Provider die Daten der API für Entwickler und Endbenutzer sicher hält und so könnte es sein, dass die API mehrere Authentifizierungsschemen hat. Die API-Dokumentation erklärt jede Authentifizierungsmethode, so dass Benutzer verstehen, wie Sie auf die API zugreifen.

Endpunkt-Definition

API-Endpunktdefinitionen sind der Punkt, an dem sich die API mit dem Softwareprogramm verbindet. Der Punkt, an dem die API mit einem anderen System interagiert wird als Endpunkt betrachtet, und kann eine URL des Servers oder Service enthalten.

Status- und Fehlercodes

Status- und Fehlercodes werden von APIs verwendet, um Entwickler zu informieren, wenn die API nicht wie erwartet ausgeführt wird, neben einer Beschreibung des Status oder Fehler. Sie können Anweisungen enthalten, wie man damit umgehen und alle auftretetenden Fehler lösen kann.

Beispiele

Wenn Benutzer verstehen, wie die API funktioniert, ist es gut, ihnen Beispiele zu geben, die erfolgreiche Beispiele für Aufrufe, Antworten, Fehlerbehandlung und andere Operationen vermitteln, die bei der Verwendung der API auftreten könnten.

Glossar

Anstatt alle technischen Begriffe in Ihrer Dokumentation zu erklären, können Sie auf ein Glossar verlinken, das Definitionen für Begriffe, Schemas und mehr bietet.

So schreiben Sie Ihre erste API-Dokumentation

Die Zielgruppe erkennen

Bevor Sie mit der Erstellung einer API-Dokumentation beginnen, sollten Sie sicherstellen, dass Sie die beabsichtigte Zielgruppe für Ihr Produkt verstehen. Sie müssen genau wissen, auf welche Art von Benutzern Sie sich konzentrieren möchten, welche speziellen Vorteile sie von der API erhalten werden, und die Art und Weise, wie sie Ihre Dokumentation in diesem Bereich verwenden.

Es ist wichtig zu bedenken, dass Ihre potentielle Zielgruppe für Ihre API-Dokumentation typischerweise in zwei Gruppen geteilt werden kann. Der erste ist die Entwickler, die mit der API interagieren und sie aktiv nutzen werden , die mehr Dokumentation benötigen, wie Tutorials und Code-Beispiele. Die zweite Gruppe besteht aus technischen Führern und Produktmanagern, die die API bewerten und dabei abwägen, wie diese< ihren Geschäftszielen entspricht.

Erstellen Sie einen Aktionsplan für Benutzer

Wenn Benutzer mit Ihrer API-Dokumentation interagieren, können sie sich in einer von vielen Phasen der Benutzererfahrung befinden. Benutzer, die Ihre API zuerst bewerten, benötigen eine Dokumentation, um ihnen genau mitzuteilen, was Ihre API genau machen kann, die Probleme, die es löst, Definitionen von Funktionen und Endpunktenm und wie Ihre API sich von anderen bestehenden Anbietern unterscheidet.

Mit der Erstellung eines Aktionplans für Ihre Benutzer können Benutzer auf verschiedenen Stufen versorgt werden und so kann eine bessere Entwicklungserfahrung geliefert werden. Entwickler werden jeden Schritt des Weges unterstützt, anstatt sich zu fragen, was Ihre API für sie tun kann.

Beginnen Sie mit Richtlinien für gewöhnliche Szenarien

Es gibt einige der häufigsten Funktionen, für die Ihre API verwendet wird, damit Sie Richtlinien für diese Szenarien erstellen können. Sie müssen sicherstellen, dass Sie typische Anwendungsfälle für Ihre API ansprechen, damit neue Entwickler die Möglichkeit haben verstehen, wie die API richtig genutzt wird. Jeder Anwendungsfall sollte einen separaten Abschnitt haben und jeweils eine Beispielnachricht enthalten.

Die Bereitstellung von Richtlinien für übliche Szenarien wird Ihren Entwicklern helfen, ihre Arbeit in Gang zu setzen, ohne zu viel dafür alleine kämpfen zu müssen. Es zeigt auch Entwicklern, wozu Ihre API fähig ist und kann sie überzeugen, Ihre API über andere zu wählen.

Beispiele des Codes hinzufügen

Das Hinzufügen von Code-Beispielen zu Ihrer API-Dokumentation hilft Entwicklern beim schnellen Ausprobieren Ihrer API und dabei, sein volles Potenzial zu verstehen. Jeder Endpunkt sollte mit eigenen Code-Beispielen versehen sein, sodass der Entwickler den Code anpassen kann, um seine genaue Anforderungen zu erfüllen und die wichtigsten Funktionen des Endpunkts auszuprobieren

Code-Beispiele zeigen potentiellen Entwicklern, wie Ihre API funktioniert und erleichtert es ihnen loszulegen, weil sie den Code einfach kopieren und einfügen können. Sie können Code-Beispiele in die verschiedenen Programmierungssprachen einfügen, in denen Ihre API verfügbar ist.

Abruf Fehlermeldungen und Statuscodes

Fehlermeldungen und Statuscodes sollten in Ihrer Dokumentation enthalten sein, da sie Ihren Entwicklern mitteilen , wenn sie einen erfolgreichen API-Aufruf durchgeführt haben oder nicht. Jede Nachricht oder Code sollte in einer kurzen Textbeschreibung angeben, warum sie angezeigt wird, damit Benutzer verstehen können, was passiert, wenn sie mit dem System interagieren,

Beschreibungen, die mit Fehlermeldungen einhergehen, sollten mit dem Ziel erstellt werden, Benutzern zu zeigen, wie sie die Probleme selbst lösen können. Sie sollten detailliert und spezifisch sein, damit Benutzer verstehen können, warum das System einen Fehler anzeigt.

Ihre Dokumentation beibehalten

Nachdem Sie Ihre Dokumentation zum ersten Mal veröffentlicht haben, müssen Sie sicherstellen, dass Sie sie regelmäßig erneut besuchen, um Ihren Inhalt auf den aktuellsten Stand zu halten. Nichts erschreckt potentielle Benutzer Ihrer API mehr als eine Dokumentation, die inkomplett oder ungenau ist.

Ohne effektive Dokumentation im Laufe der Zeit werden Entwickler Ihre API nicht verwenden können und Sie erleben eine Senkung bei der Aufnahme. Jedes Mal, wenn Sie ein Update oder eine neue Funktion erstellen, sollte dies in der Dokumentation reflektiert sein und als wesentlicher Bestandteil des Versands Ihrer API angesehen werden.

Bewährte Praktiken für die API-Dokumentation

1. Klare Sprache verwenden

Beim Schreiben der API-Dokumentation wissen Sie nicht, welche Expertise die Benutzer Ihrer Dokumentation haben wird. Deshalb ist es wichtig, eine klare, einfache Sprache zu verwenden, die jeder verstehen kann.

2. Referenzdokumentation einschließen

Referenzdokumentation für APIs ist eine umfassende Liste von Objekten und Methoden, die von der API belichtet werden, zusammen mit einer Beschreibung, wie man jede einzelne verwendet. Dies lehrt Entwickler über alles, was verfügbar ist und wie es funktioniert.

3. Beispiele einsetzen

So oft wie möglich sollten Sie Beispiele dafür verwenden, wie Ihre API funktioniert, die in jeder Referenzbereich Ihrer Dokumentation gefunden werden können. Es kann alles sein, was das Konzept der API illustriert und Entwicklern hilft, mit ihren eigenen API-Aufrufenzu beginnen.

4. Beauftragen Sie jemanden für die Dokumentation

Sie brauchen jemanden in Ihrem Team, dessen Aufgabe es ist, die Entwicklererfahrung Ihrer API-Dokumentation zu überwachen. Es könnte ihr Hauptauftrag sein, ob sie ein technischer Autor oder teilzeitig dafür verantwortlich sind, wenn sie auch eine Rolle als Entwickler spielen.

5. Verschiedene Arten und Themen abdecken

Sie müssen sicherstellen, dass Ihre API-Dokumentation umfassend ist und dass sie Referenzen, Leitfäden und Beispiele einschließt. Wenn bestimmte Bereiche fehlen, werden Sie diese Informationen nutzen, um zu entscheiden, wo Sie zukünftige Bemühungen fokussieren sollen.

6. Dokumentation in Prozesse einbauen

Ihre Dokumentation und Ihre API sollten sich parallel entwickeln. Mit der Entwicklung der API kommt die Entwicklung Ihrer Dokumentation, insbesondere neben der Einführung von neuen Features.. Automatisieren Sie so viel wie möglich und sparen Sie mit Ihrer Dokumentation Zeit.

7. Geben Sie Schnellstart-Anleitungen an

Schnellstart-Anleitungen sind die beste Möglichkeit, neue Entwickler mit Ihrer API an Bord zu nehmen und sie mit der Verwendung Ihrer API einzuleiten. Sie enthalten Anweisungen, wie Sie Ihre API verwenden können, sowie Code-Beispiele, die den Zugriff auf Ihre API wesentlich vereinfachen.

Besuchen Sie auch unseren Blog zur API Dokumentations-Checkliste

Beste Beispiele für API-Dokumentation

Hier sind einige Beispiele für echte API-Dokumentation, die Sie verwenden können, um Ihre eigenen Bemühungen zu inspirieren.

GitHub API

Die GitHub API ist eine REST API, durch die Entwickler eine Verbindung mit der GitHub Plattform herstellen können. Sie ist auch ein gemeinschaftliches Entwicklungstool für Software-Projekte. GitHub bietet eine ausführliche Schnellstart-Dokumentation, um den Entwicklern zu helfen, sich mit der API und detaillierten Abschnitten für jeden Aspekt der API-Verwendung zu befassen.

Twilio API Dokumentation

Twilios API ist eine weitere REST-API, die Entwickler verwenden können, um sich mit der Twilio-Plattform zu verbinden – eine Kundenengagement-Plattform, die Unternehmen in die Lage versetzt, in großem Umfang zu kommunizieren. Die Dokumentation enthält alles, was Sie mit Twilio integrieren möchteb, einschließlich der Authentifizierung mit HTTP und SDKs.

Dropbox API Dokumentation

Die Dropbox API ermöglicht Entwicklern Integrationen mit der Dokumentenaustauschplattform von Dropbox zu erstellen. Es bietet vorgefertigte Komponenten, zusammen mit einer API-Referenz, die Entwicklern die Erstellung maßgeschneiderter Anwendungen und Integrationen ermöglicht. Es bietet auch mehrere offizielle SDKs für populäre Programmiersprachen.