Beim Kauf neuer Elektronik, wie z. B. eines neuen Laptops, finden Sie eine Bedienungsanleitung im Karton. Die Bedienungsanleitung enthält Anweisungen, damit Sie verstehen, wie Sie den Laptop und alle Funktionen, die er bietet, bedienen können.
Eine API (Application Programming Interface) kann man sich wie ein Gerät vorstellen, nur dass es sich um ein Werkzeug handelt, das zum Verbinden von Software verwendet wird. Mit einer in einer Computersprache festgelegten API ist es anfangs möglicherweise nicht so einfach zu verstehen. Wie können Benutzer also überhaupt APIs nutzen?
API-Entwickler haben es sich zur Gewohnheit gemacht, eine Benutzerhandbuch für verteilte APIs bereitzustellen. Dieses Benutzerhandbuch wird im Allgemeinen als API-Dokumentation angesehen!
Was ist API-Dokumentation?
API-Dokumentation ist technischer Inhalt, der geschrieben wurde, um detailliert zu beschreiben, wie eine API funktioniert. Sie enthält Anweisungen zur Nutzung der API, informiert im Allgemeinen über den Nutzungsumfang der API und welche Ergebnisse sie liefern kann. Für Entwickler kann die API-Dokumentation als Benutzerhandbuch für die Arbeit mit der API angesehen werden.
Ein Beispiel, bei dem API-Dokumentation benötigt wird, wäre, wenn ein Entwickler plant, eine Wetteranwendung zu erstellen. Der Entwickler kann sich dann auf die Dokumentation einer Wetter-API beziehen, um zu sehen, welche Eingaben und Ausgaben möglich sind, und so dem Entwickler ermöglichen, wetterbezogene Anwendungen für Benutzer wie uns zu erstellen!
Eine gute API-Dokumentation kann Entwicklern in vielerlei Hinsicht zugute kommen. Am offensichtlichsten wäre die Zeitersparnis in der Entwicklungsphase. Nützliche API-Dokumentation enthält Codebeispiele, die sofort verwendet werden können, sodass der Entwickler mit dem Testen der API-Ausgabe in seiner Anwendung beginnen kann. Die Produktivität steigt für alle, auch für Sie und Ihre Kollegen.
Wer wird API-Dokumentation verwenden?
API-Dokumentation ist für jeden nützlich, der beabsichtigt, Ihre API als Teil seiner Software zu nutzen. Wenn die von Ihnen entwickelte API ein bestimmtes Thema wie Aktienkurse hat, können Sie erwarten, dass Softwareentwickler für Aktien Ihre API-Dokumentation lesen.
Allein durch das umgebende Thema Ihrer API können Sie bereits die Art der potenziellen Benutzer antizipieren, die Sie anziehen werden, aber was sicherer ist, ist, dass es sich um Softwareentwickler handelt, also achten Sie auf die Fachsprache und den Jargon, der zur Beschreibung Ihrer API verwendet wird.
Wie schreibt man eine gute API-Dokumentation?
API-Dokumentation enthält wesentliche Komponenten, die für ihre Leser erforderlich sind, um zu verstehen, wie die API funktioniert. Um jedoch alles ordnungsgemäß in die Dokumentation für Ihre Leser aufzunehmen, müssen Sie Folgendes tun:
Verstehen Sie Ihre API
Wenn Sie nicht wissen, was Ihre API benötigt oder was Ihre API tut, wie schreiben Sie dann Ihre API-Dokumentation? Sie sollten in der Lage sein, anzugeben, was Ihre API beinhaltet, und können Beschreibungen wie mögliche Antworten, Parameter, akzeptierte Datentypen und verschiedene Anwendungsfälle enthalten, in denen Sie sehen, dass Ihre API potenziellen Nutzen hat.
Geben Sie eine detaillierte Beschreibung für die Anwendungsfälle Ihrer API an
Nehmen Sie sich bei der Erstellung Ihrer API-Dokumentation etwas Zeit, um darüber nachzudenken, für welche Szenarien Ihre API am wahrscheinlichsten gelten würde. Stellen Sie sicher, dass Sie angeben, welche Parameter Ihre API benötigt, welchen Datentyp sie zurücksendet und welche Einschränkungen festgelegt sind. Die Bereitstellung von Codebeispielen für verschiedene Computersprachen wäre für Entwickler ebenfalls eine große Hilfe, da dies Zeit und zusätzliches Tüfteln spart.
Identifizieren Sie die Benutzer Ihrer API
Berücksichtigen Sie bei der Erstellung Ihrer API folgende Frage: „Wer wird meine API verwenden?“. Wenn Sie Ihre API ins Internet hochladen, kann praktisch jeder Ihre API nutzen. Dies würde bedeuten, dass Ihre API die allererste API von jemandem sein kann, daher sollte ein Gleichgewicht zwischen der technischen Ausrichtung und der Einfachheit der Sprache berücksichtigt werden. Am wichtigsten ist, dass Entwickler Ihre API in ihre Anwendungen implementieren können sollten, sobald sie Ihre API-Dokumentation gelesen haben.
Aktualisieren Sie Ihre API-Dokumentation
Die Technologie ist eine schnelllebige, sich ständig weiterentwickelnde Branche, und natürlich wird dies auch Ihre API sein! Ein weiterer möglicher Grund für die Aktualisierung der API-Dokumentation wären Updates der Computersprache, wodurch alte Codes unbrauchbar werden. Mit jeder neuen Version Ihrer API sollte eine Überarbeitung Ihrer API-Dokumentation vorbereitet werden. Dies ermöglicht es Entwicklern, Ihre API mit Zuversicht zu verwenden, da dies signalisiert, dass Ihre API eine zuverlässige Wartung hat.
Gutes Beispiel für die Struktur der API-Dokumentation
Wenn Sie neugierig sind, wie eine gute API-Dokumentation aussieht, sehen Sie sich die PayPal-API-Dokumentation für Entwickler an. Zuerst wird eine präzise Beschreibung angezeigt, die angibt, welche Dienste die API bereitstellen kann.
Es werden weitere technische Komponenten wie die Sicherheit, die Anfrage und die Anzahl der Antworten der API bereitgestellt. Sie können feststellen, dass sie eine Einschränkung hinsichtlich der Anzahl der Tracking-IDs angegeben haben, die sie akzeptieren können. (Sicherheit und Anfrage wurden aufgrund ihrer Länge nicht erweitert.)
Auf derselben API-Dokumentationsseite finden Sie Codebeispiele für verschiedene Clientsprachen zur API-Implementierung und mögliche Fehlerbeschreibungen, auf die Sie bei der Verwendung der API stoßen können. Entwickler können diese Codebeispiele an geeigneter Stelle einfügen und dann mit dem Testen ihrer Anwendung beginnen. (Die Anfrage- und Antwortbeispiele werden aufgrund ihrer Länge nicht erweitert.)
Schließlich werden Definitionen und ihre jeweiligen Details zu allen möglichen Parametern im Datenschema in der API-Dokumentation bereitgestellt. In dem bereitgestellten Bild werden der Datentyp und die Erweiterung der beobachtbaren Ausgabe angezeigt.
Mit einer klaren und beschreibenden API-Dokumentation sind Entwickler bereit, diese PayPal-Tracking-API in ihre Anwendungen zu integrieren. Viele andere API-Dokumentationen weisen optimale API-Dokumentationsmerkmale auf. Weitere bemerkenswerte Beispiele, auf die Sie sich beziehen können, wenn Sie nach leicht verständlicher API-Dokumentation suchen, sind Google Maps, Twilio und Twitter.
Beispiel für unerwünschte API-Dokumentation
Im Folgenden finden Sie ein Beispiel für eine API-Dokumentation, die einige Entwickler online geteilt und als eine der am schwierigsten zu verstehenden API-Dokumentationen bezeichnet haben. Versuchen Sie, einen Blick darauf zu werfen und zu sehen, ob Sie verstehen können, wofür die API verantwortlich ist.
Fiel es Ihnen schwer zu verstehen, was die API erreichen soll? Sie werden möglicherweise schnell feststellen, dass der API-Entwickler keinerlei Beschreibung für die API bereitgestellt hat. Diese Art von API-Dokumentation lässt erfahrene Entwickler raten, was sie tut und wo sie sie verwenden sollen!
Darüber hinaus wird die Computersprache nicht angegeben (z. B. JavaScript oder Python). Schließlich lässt der Mangel an Fehlererklärungen Entwickler ratlos zurück, wenn sie auf einen stoßen. Der Mangel an Details behindert den Fortschritt der Softwareentwicklung, da der Entwickler verstehen muss, wie die API implementiert wird. Dies ist der Grund, warum eine klare API-Dokumentation von vielen Entwicklern geschätzt wird!
Was sollte in der API-Dokumentation enthalten sein?
Es gibt beobachtbare wesentliche Komponenten in einer effektiven API-Dokumentation. Diese Variablen trennen die gute API-Dokumentation von der schlechten:
Klare Übersicht und Zweck Ihrer API
Sagen Sie sofort, was Ihre API leisten kann. Entwickler möchten wissen, was Ihre API ihnen bieten kann, also überspringen Sie das Drumherum. Gute API-Übersichten gehen normalerweise nicht über drei Sätze hinaus, also bereiten Sie sich darauf vor, die Komponenten, den Anwendungsfall und den Nutzen der API zu verdichten.
HTTP-Antwortcodes und Fehlermeldungen
Entwicklern mitzuteilen, welche spezifische HTTP-Antwort verarbeitet wurde, und sie mit der richtigen Fehlermeldung zu verknüpfen, ist von entscheidender Bedeutung. Entwickler können entsprechend dem Code codieren, was Ihre API potenziell antworten kann.
Anfrage- und Antwortformate
Entwickler schätzen den Gedanken von API-Dokumentationsautoren, Beispielanfragen und -antworten bereitzustellen, da sie es ihnen ermöglichen, ihren Code so zu konfigurieren, was verarbeitet werden kann und was nicht.
Abfrageparameter
Geben Sie explizit an, welche Art von Parametern Ihre API zusammen mit den Datentypen erwartet. Auf diese Weise müssen Entwickler keine Zeit damit verschwenden, zu testen, welche Datentypen akzeptiert werden.
Code-Snippets
Code-Snippets sind besonders nützlich für neuere Entwickler, die gerade erst lernen, wie man APIs verwendet. Indem Sie Code-Snippets in verschiedenen Clientsprachen bereitstellen, sprechen Sie ein größeres Publikum von Entwicklern an, da Entwickler auf der ganzen Welt unterschiedliche Clientsprachen verwenden können.
Wo können wir API-Dokumentation schreiben? - Apidog
Viele API-Entwicklungsplattformen ermöglichen es ihren Benutzern, eine entsprechende Dokumentation für ihre API zu schreiben. Sie haben möglicherweise von ADI-Plattformen oder -Tools wie Postman, Swagger und Document360 gehört oder diese verwendet, aber eine Demonstration einer neuen API-Plattform namens Apidog.
Der Grund, warum Apidog bei der Erstellung der API-Dokumentation demonstriert wird, ist die gleichzeitige Erstellung der API-Dokumentation während der Entwicklung der API.
Apidog bietet auch viel Komfort in der API-Dokumentation, z. B. die Anzeige zahlreicher Arten von Beispielanfragen in zahlreichen gewünschten Clientsprachen, gekoppelt mit möglichen Antworten, die Entwickler erhalten können. Apidog enthält auch Echtzeit-Updates, die in der API-Dokumentation widergespiegelt werden, die an Benutzer mit dem verteilbaren API-Dokumentations-Weblink-System verteilt wird.
Erstellen von API-Dokumentation mit Apidog
Wenn Sie daran interessiert sind, zu lernen, wie Sie mit Apidog API-Dokumentation erstellen, stellen Sie sicher, dass Sie zuerst unsere Software herunterladen, klicken Sie einfach auf die Schaltfläche, und Sie werden weitergeleitet!
Schritt 1 – Melden Sie sich mit der verfügbaren Methode an
Melden Sie sich mit einem Konto an, das Sie bevorzugen, um Apidog zu verwenden. Sie können ein Gmail- oder ein anderes E-Mail-Konto verwenden, um sich anzumelden, oder wenn Sie lieber Ihr GitHub-Konto verwenden möchten, tun Sie dies bitte.
Schritt 2 – Erstellen Sie ein neues Projekt
Sobald Sie sich angemeldet haben, sollten Sie mit dem Standardbildschirm „Mein Arbeitsbereich“ begrüßt werden, auf dem Sie ein Beispielprojekt sehen können. Um mit der Erstellung Ihrer eigenen API und der entsprechenden API-Dokumentation zu beginnen, klicken Sie auf „Neues Projekt“ in der oberen linken Ecke des Apidog-Fensters.
Achten Sie darauf, Ihrem neuen Projekt einen sinnvollen Namen zu geben.
Schritt 3 – Erstellen Sie eine neue API
Da es sich um ein brandneues Projekt handelt, beginnen Sie mit der Auswahl von „Neue API“. Felder warten auf Ihre Eingabe, also beginnen Sie mit der Erstellung Ihrer allerersten API mit Apidog! (Natürlich wird empfohlen, Informationen zu allen Feldern bereitzustellen, die Apidog hat. Am Ende sieht es kohärent und elegant aus.)
Schritt 4 – Speichern Sie Ihre API
Stellen Sie abschließend sicher, dass Sie Ihren gesamten Fortschritt bei der Entwicklung der API gespeichert haben.
Das Schöne an Apidog ist, dass die Benutzeroberfläche sofort als API-Dokumentation fungiert. Sie können alle Beschreibungen Ihrer API sehen, sobald Sie auf die Schaltfläche „Speichern“ klicken. Antwort- und Codebeispiele sowie API-Pfad und Abfrageparameter sind alle fertig!
Um mehr zu erfahren, können Sie sich den umfassenden Leitfaden zum Generieren von API-Dokumentation mit Apidog ansehen.
Gute API-Dokumentation ist revolutionär
Zusammenfassend lässt sich sagen, dass das Wissen, wie man eine gute API-Dokumentation schreibt, jedem zugute kommt, der Ihre API verwenden möchte. Detaillierte API-Dokumentation kann die Produktivität der Entwickler steigern und gleichzeitig enorme Mengen an Zeit sparen. Am Ende des Tages sind wir es, die von den schönen und lebensverbessernden Apps profitieren, die nur mit APIs möglich sind!
