„Hallo Welt“

Anleitung zur Erstellung einer API-Dokumentation

Peter Gruenbaum

Hat Ihr Manager Sie jemals gebeten, eine Dokumentation für die von Ihnen entwickelten APIs zu schreiben? Hand aufs Herz – wenn es Ihnen wie den meisten Entwicklern geht, dann lieben Sie es, Code zu schreiben, und hassen es, die Dokumentation zu erstellen. Außerdem hindert Sie das Erstellen der Dokumentation daran, wichtige Aufgaben fertig zu stellen, wie die Entwicklung von Funktionen und das Beheben von Fehlern.

Es ist daher keine Überraschung, dass die Dokumentation der API häufig frustrierend und für den Leser schwer verständlich ist, da sie selten die Aufmerksamkeit erhält, die nötig ist.

In diesem Artikel finden Sie eine Anleitung für die Erstellung einer API-Dokumentation. Ich werde die wichtigsten Komponenten einer API-Dokumentation beschreiben und einige Vorschläge dazu machen, wie Sie diese effektiver machen können. Ich gebe Ihnen außerdem einige Hinweise, wie Sie gute Übersichten, Beispielcode und Referenzmaterialien erstellen, und worauf Sie sich konzentrieren sollten, um die beste Wirkung zu erzielen.

Warum eine Dokumentation für Ihre APIs?

Lassen Sie uns mit dem nicht technischen Aspekt beginnen. API-Dokumentationen gibt es, seit es Programmiersprachen gibt. Es gab jede Menge Zeit, um effektive Prozesse für das Erstellen qualitativ anspruchsvoller Dokumentationen zu entwickeln; gut geschriebene API-Dokumentationen sind jedoch nach wie vor selten. Warum ist das so?

Zum einen erhalten Dokumentationen selten Priorität. Obwohl eine Dokumentation großen Einfluss auf den Erfolg einer Softwareplattform hat, kann der tatsächliche Beitrag der Dokumentation nur schwer ermittelt werden. Daher wird für Dokumentationen selten genügend Zeit und Geld aufgewendet. Wenn Entwickler aufgefordert werden, eine Dokumentation zu erstellen, dann kommt dies in der Regel zu ihren anderen Aufgaben hinzu, und sie müssen diese Aufgabe irgendwie in ihren bereits übervollen Zeitplan einschieben.

Zum anderen setzen das Entwickeln von Code und das Schreiben einer Dokumentation ganz unterschiedliche Fähigkeiten voraus. Manchmal müssen Entwickler in einer Sprache schreiben, die nicht ihre Muttersprache ist. Aber selbst wenn sie in einer englischsprachigen Region geboren wurden und auf Englisch schreiben, sind die Chancen groß, dass sie Schwierigkeiten in den sprachlichen Fächern hatten und ihre Zeit lieber mit der Lösung von Aufgaben in Mathematik und Naturwissenschaften verbrachten.

Der erste Schritt bei der Erstellung einer guten API-Dokumentation besteht darin, das Management nach genügend Zeit und einem ausreichenden Budget zu fragen, um die Aufgabe gut lösen zu können. Es gibt zwei Argumente, die Sie Ihren Managern vortragen können:

1. Eine gute Dokumentation kann den Erfolg einer Plattform steigern, da die Entwickler weniger frustriert im Hinblick auf die Entwicklungsumgebung sind.
2. Eine gute Dokumentation senkt die Supportkosten, da die Entwickler die Antworten auf ihre Fragen leichter selbst finden können.

Die Argumentation für eine gut geschriebene Dokumentation kann eine Herausforderung für Sie bedeuten, wenn Sie nicht gerne Texte verfassen oder völlig mit Arbeit überlastet sind, aber es gibt eine andere Möglichkeit. Wenn das Budget hierfür ausreicht, können Sie einen technischen Autor beauftragen, der Informationen von Ihnen sammelt und die Dokumentation erstellt.

Wie bei Entwicklern, gibt es auch bei den technischen Autoren eine große Bandbreite von Erfahrung und Wissen. Zahlreiche technische Autoren haben mehr Erfahrung mit Dokumentationen und Hilfesystemen für Endbenutzer. Für eine API-Dokumentation sollten Sie jedoch einen technischen Autor finden, der einige Zeit als Software-Entwickler gearbeitet hat. In vielen Unternehmen haben diese Mitarbeiter Titel wie „Programmierer/Autor“.

Technische Autoren mit Programmiererfahrung verstehen die Probleme, die Entwickler bei der Entwicklung einer Softwareplattform haben, und dass eine gute Dokumentation dazu beitragen kann, die Entwicklung der Plattform zu verbessern. Außerdem verfügen sie wahrscheinlich über ein entsprechendes Wissen im Hinblick auf Sprachen, Algorithmen und Muster, sodass sie Ihren Code lesen und Ihre Bibliotheken verstehen können. Mit diesem Wissen und dieser Erfahrung gestalten sich die Diskussionen zu technischen Themen zwischen dem Autor und dem Entwicklerteam einfacher und produktiver.

Wenn das Budget nicht ausreicht, um einen technischen Autor mit der Erstellung der Dokumentation zu beauftragen, müssen Sie diese selbst erstellen. Stellen Sie sicher, dass das Management versteht, dass Sie hierfür Zeit benötigen, genauso, wie Sie Zeit benötigen würden, um eine neue Funktion zu entwickeln.

Komponenten einer API-Dokumentation

Eine gute API-Dokumentation hat vier Komponenten:

1. Überblick: Erklären Sie die Vorteile, die diese Plattform für Entwickler hat, und in einigen Fällen sollten Sie eine Beschreibung der Architektur der Plattform zur Verfügung stellen.
2. Erste Schritte: Unterstützen Sie den Entwickler bei den ersten Schritten, indem Sie Schritt-für-Schritt-Anleitungen oder eine einfache Übersicht über die Verfahren bereitstellen.
3. Beispielcode: Stellen Sie gut kommentierte Codebeispiele bereit, mit den Entwickler arbeiten können.
4. Referenzmaterial: Stellen Sie detaillierte Informationen über die einzelnen Klassen, Elemente, Funktionen oder XML-Elemente bereit.

Wenn Entwickler mit dem Lesen der Dokumentation über eine API beginnen, müssen sie die folgenden Informationen als erste erhalten: Wer sollte die API verwenden, und warum sollte sie verwendet werden? Wenn ein Entwickler nicht versteht, was Sie hierzu schreiben, dann wird er schnell nach einer alternativen Lösung suchen. Leider werden diese Informationen häufig vergessen. Für die Entwickler, die diese API entwickeln, sind die Antworten offensichtlich – aber nicht für andere Entwickler.

Geben Sie klare Beispiele dafür, wann die API verwendet werden sollte. Wenn es bereits Kunden gibt, oder potenzielle Kunden, verwenden Sie diese als praktische Beispiele. Listen Sie die Vorteile der Softwareplattform auf. Ideal ist es, wenn Sie diese mit vorhandenen Ansätzen vergleichen. Häufig verfügen die Projektleiter über diese Art von Informationen.

Übersichten sind auch gut geeignet, um die Gesamtarchitektur einer API zu erklären. Einige Arten von APIs (z. B. zahlreiche Web-APIs) sind so einfach, dass die Architektur nicht behandelt werden muss. Wenn Sie jedoch komplexe APIs dokumentieren, die über zahlreiche Klassen und eine vererbte Struktur verfügen, ist eine vollständige Behandlung der Architektur, die auch Diagramme enthält, häufig hilfreich, damit Entwickler diese auch verstehen.

Erste Schritte

Wenn Entwickler sich entschieden haben, mit Ihrer API zu arbeiten, möchten sie als Erstes wissen, wie sie am besten beginnen. Im Jahr 2009 führte mein Unternehmen, (SDK Bridge LLC) eine Umfrage zu Dokumentationen durch, und es wurde von den Antworten her offensichtlich, dass Entwickler Unterstützung zu Beginn der Arbeit mit einer API wünschen. (Weitere Informationen hierzu finden Sie in meinem Artikel „Survey on SDK Documentation“ (Umfrage zur SDK-Dokumentation) unter tinyurl.com/35l66yk). Dies ist wichtig für die allgemeine Akzeptanz. Wenn Entwickler es schwierig finden, den Anfang zu machen, geben sie schnell auf und suchen nach einer anderen Möglichkeit, ihre Ziele zu erreichen.

Eine gute Möglichkeit, Entwicklern beim Start zu helfen, sind Anleitungen, oder Lernprogramme. Dieser Ansatz ist häufig effektiver als eine Beschreibung oder Architekturdiagramme. Ein Lernprogramm führt den Entwickler Schritt für Schritt durch den Prozess der Erstellung einer einfachen Anwendung und zeigt ihm, wie die API funktioniert. Es beginnt häufig mit der Beschreibung nicht programmierbezogener Aktivitäten, wie die Einrichtung der Umgebung oder dem Erhalt der Anmeldeinformationen für die Autorisierung. Anschließend wird dem Entwickler gezeigt, wie er Code hinzufügen kann, bis mithilfe dieser API eine einfache Aufgabe gelöst werden kann. Versuchen Sie, Ihr Lernprogramm so zu strukturieren, dass Entwickler schnell eine funktionierende API haben und Ergebnisse sehen. Fahren Sie anschließend mit dem Lernprogramm fort, indem Sie weitere Funktionen hinzufügen.

Möglicherweise haben Sie so viel an Ihrer API gearbeitet, dass Sie vergessen haben, wie es ist, wenn man sie von außen betrachtet. Wenn Sie an diesem Abschnitt arbeiten, sollten Sie sich in die Lage eines unbeteiligten Entwicklers versetzen.

Erstellen von Beispielcode

Eine andere, häufige Antwort in der SDK Bridge-Umfrage betraf die Bedeutung von gutem Beispielcode. Entwickler lernen, wie sie mit einer Plattform arbeiten, indem sie mit Code beginnen, von dem sie wissen, dass er funktioniert. Anschließend modifizieren sie diesen oder fügen Code hinzu. Für viele Entwickler ist es einfacher, bei der Arbeit zu lernen als durch Lesen.

Sie wissen wahrscheinlich bereits, wie Sie guten Produktionscode schreiben. Guter Beispielcode hat einige Aspekte mit gutem Produktionscode gemeinsam, aber es gibt auch einige wichtige Unterschiede. Im Allgemeinen sollte ein guter Beispielcode diesen Richtlinien folgen:

1. Wichtige Informationen sollten zusammen gruppiert werden.
2. Klarheit ist wichtiger als Effizienz oder Stabilität.
3. Einfachheit ist wichtiger als eine gut aussehende Benutzeroberfläche.

Sie können diese Richtlinien auf bestimmte Bereiche von Software anwenden und sehen, wie sich der Beispielcode im Verhältnis zu Produktionscode verhält.

Jeder Programmierer weiß, dass er niemals hart kodierte Werte im Code verwenden darf. Diese Werte sollten in Konstanten umgewandelt und an einer Stelle aufgelistet werden, die einfach zu finden, ist, wenn ein anderer Entwickler diese ändern möchte.

Dies trifft zwar auf Produktionscode zu, aber nicht auf Beispielcode. In Beispielcode sollten Sie hart kodierte Werte verwenden, um alle wichtigen Informationen so eng beieinander zu gruppieren wie möglich. Wenn Sie bewährte Verfahren für den Produktionscode anwenden und alle Konstanten zu Beginn der Datei definieren, und Entwickler eine Codezeile betrachten, die eine Konstante enthält, müssen diese zurück zum Beginn der Datei wechseln, um herauszufinden, welchen Wert diese Konstante hat. Dies kann dazu führen, dass sie den Gedanken vergessen, den sie gerade verfolgen. Zeichenfolgen, Integer, Hexadezimalwerte und andere einfache Werte sollten alle hart kodiert werden, direkt an den Stellen, an denen sie verwendet werden.

Kommentare eignen sich für Produktionscode und Beispielcode, sind jedoch nicht kritisch, wenn sie in Beispielcode verwendet werden. Alle Klassen, Elemente oder Funktionen sollten mit einer Kommentarzeile eingeleitet werden, um zu erklären, worum es sich handelt oder was die Funktion ist. Sie sollten überall dort, wo der Code nicht selbst erklärend ist, Kommentare einfügen, besonders wenn Sie Problemumgehungen oder andere ungewöhnliche Prozesse dokumentieren müssen. Die Kommentare können sich auch über mehrere Zeilen erstrecken, wenn erforderlich. Verwenden Sie vollständige Sätze, und scheuen Sie sich nicht, ausführliche Kommentare zu verfassen.

Im Allgemeinen sollten Sie alle fünf oder zehn Zeilen Code mindestens eine Kommentarzeile einfügen. Es gibt jedoch einige Ausnahmen zu dieser Regel. Code, der für das, was Sie zeigen möchten, nicht wichtig ist, muss nicht so ausführlich kommentiert werden (z. B. Code für die Benutzeroberfläche, in der die Ergebnisse der API angezeigt werden). Wenn Sie ein kleines Snippet mit nur wenigen Codezeilen schreiben, das in Referenzmaterialien verwendet wird, sind vielleicht gar keine Kommentare nötig. Wenn Sie ein sehr ausführliches Beispiel bereitstellen, das Produktionscode vergleichbar ist, kann es ratsam sein, den Umfang der Kommentare zu begrenzen.

Variablen, Klassen, Elemente und Funktionen sollten eindeutige und gut strukturierte Namen haben, unabhängig davon, ob Sie Produktions- oder Beispielcode verfassen. Wenn es um Beispielcode geht, sollten Sie dies jedoch noch konsequenter durchführen, als Sie in Produktionscode tun würden, denn hier ist Klarheit wichtiger als Effizienz. Lange und umständliche Namen können in Produktionscode Probleme verursachen, sind jedoch für Beispielcode zu empfehlen, da sie für Klarheit sorgen. Auch der Name der kleinsten Variablen sollte die Bedeutung des Elements klar machen. Verwenden Sie auf keinen Fall – auch wenn die Versuchung noch so groß ist – Namen, die keinen Sinn machen, wie „foo“, oder Namen, die nur aus einem Buchstaben bestehen.

Die objektorientierte Programmierung ist eine der besten Erfindungen in der Software-Entwicklung. Sie werde überrascht sein zu hören, dass die objektorientierte Programmierung zwar für Produktionscode höchst wünschenswert ist, jedoch nicht für Beispielcode. Der Grund hierfür ist, dass die objektorientierte Programmierung die Funktionalität so verteilt, dass Daten und Funktionen zusammen gruppiert werden, und mittels Vererbung duplizierten Code reduziert. Denken Sie daran, dass die gemeinsame Gruppierung wichtiger Elemente ein Grundsatz für die Erstellung von gutem Beispielcode ist. In objektorientiertem Code werden diese Informationen auf verschiedene Klassen aufgeteilt. Daher kann es sein, dass Entwickler eine Vererbungshierarchie durchsuchen müssen, um herauszufinden, welche Aufgabe eine Methode hat. Dies bedeutet Zeitverlust und unterbricht den Gedankengang.

Es gibt natürlich Ausnahmen. Einige APIs erfordern objektorientierten Code, um korrekt zu funktionieren. Für umfangreichen Beispielcode, der mehr einer Produktionsanwendung gleicht, ist möglicherweise ebenfalls objektorientierte Programmierung erforderlich. Denken Sie in diesem Fall daran, dass Benutzer alle notwendigen Informationen in einer einzigen Klasse finden möchten, wenn möglich.

Ein Grundsatz für einen guten Software-Entwurf besteht in der Einkapselung von Funktionalität in Funktionen und Methoden. Im Fall von Produktionscode sorgt dies für mehr Klarheit und reduziert duplizierten Code. Dieses Verfahren eignet sich auch gut für Beispielcode, da häufig ein Codeblock erstellt werden kann, den Entwickler kopieren und in ihren eigenen Code einfügen können. Dies erleichtert die Anwendung.

Manchmal erfordert Beispielcode eine große Zahl von Codezeilen, die nicht direkt für Ihre API relevant sind, die aber für die Ausführung des Beispielcodes benötigt werden. In diesem Fall ist es eine gute Idee, diese Codezeilen in einer Funktion oder einer Methode zu kapseln, sodass es für Entwickler einfacher ist, sie zu ignorieren.

Die Benutzeroberflächenelemente im Beispielcode sollten so einfach gehalten werden wie möglich, es sei denn, die API stellt Benutzeroberflächenfunktionen bereit, die Sie vorführen müssen. Benutzeroberflächencode kann sehr viel Platz beanspruchen und von den wichtigen Codezeilen ablenken, die Sie vorführen möchten. Entwickler interessiert es nicht, ob Ihr Beispiel gut aussieht, sie möchten nur verstehen, wie die API funktioniert.

Wenn Sie die Verwendung einer großen Anzahl von Codezeilen für die Oberfläche nicht vermeiden können, kapseln Sie diesen Code in eigene Funktionen, die leicht von Entwicklern durchgesehen oder ignoriert werden können.

Und schließlich kann die Ausnahmebehandlung wichtig für die korrekte Ausführung von Code sein. In Beispielcode kann sie jedoch den Fokus von den wichtigen Codeteilen nehmen und von diesen ablenken. Häufig besteht die Lösung nicht in der Verwendung von Ausnahmebehandlung, sondern darin, einen Kommentar einzufügen, in dem erklärt wird, welche Arten von Ausnahmen im Produktionscode behandelt werden müssen. Es gibt jedoch Fälle, in denen bestimmte Aufrufe stets mit Ausnahmebehandlung erfolgen sollten, und dann ist es die zusätzlichen Zeilen Code wert, um genau zu zeigen, wie diese Ausnahmebehandlung aussehen sollte.

Abbildung 1 zeigt ein Beispiel für eine Funktion aus einem Beispielcode, in dem gezeigt wird, wie REST-Anfragen in C# für die Website eines sozialen Netzwerks aussehen sollten, indem die Benutzer-IDs der verbundenen Benutzer dem angegebenen Benutzer zurückgegeben werden. In Produktionscode würde die Endpunkt-URL der REST-Anfrage zusammen mit anderen relevanten URLs als Konstante gespeichert werden. In Beispielcode sollten diese Informationen jedoch dort angezeigt werden, wo Entwickler sie am wahrscheinlichsten sehen und die Rolle in der Funktion erkennen können. Beachten Sie auch, dass die Fehlerbehandlung vorgeschlagen, jedoch nicht implementiert ist. Die XML-Verarbeitung wurde aus Kürzungsgründen aus diesem Beispiel entfernt.

Abbildung 1 Beispielcode

/// <summary>
/// Returns an array of user IDs for users that 
/// are connected to the specified user. Note that 
/// this is a simple, synchronous way to obtain the data.
/// </summary>
/// <param name="userId">The ID of the specified user.</param>
/// <returns>An array of user IDs that are connected to 
/// the specified user.</returns>

public int[] GetConnectedUserIds(int userId) {
  // Create variable to hold the returned IDs
  int[] connectedIds;

  // Construct a URL using the userId and the authorization token
  string url = 
    "http://webservices.contoso.com/users/connections?userid=" + 
    userId.ToString() +
    "&token=" + 
    authorizationToken;

  // Create the Web request using the url
  HttpWebRequest request = 
    WebRequest.Create(url) as HttpWebRequest;
 
  // Get the response
  using (HttpWebResponse response = 
    request.GetResponse() as HttpWebResponse) {

    // Read the response XML
    StreamReader reader = 
      new StreamReader(response.GetResponseStream());
    string xmlResponse = reader.ReadToEnd();

    // Process XML to extract user IDs for connected users 
    // and responseStatus
    ...

    if (responseStatus != "ok") {
      // Handle errors here
      ...
    }

    reader.Close();
  }

  return connectedIds;
}

Referenzmaterial

Der größte Teil der API-Dokumentation besteht in der Regel aus Referenzmaterial. Für jede Klasse, jedes Element, jede Funktion, jedes XML-Element usw. müssen detaillierte Informationen zur Aufgabe und Verwendung vorhanden sein. Das Referenzmaterial muss mindestens die folgenden Punkte abdecken:

• Kurze Beschreibung
• Beschreibung aller Parameter und Wiedergabewerte
• Alle wichtigen Hinweise, die den Entwickler bei der Arbeit unterstützen können

Wenn genügend Zeit und Geld vorhanden sind, fügen Sie die folgenden Informationen hinzu:

• Ausnahmen, die abgefangen werden müssen
• Links zu verwandten Übersichten oder Referenzthemen
• Ein Snippet eines Beispielcodes, idealerweise von dem Beispielcode, den Sie bereits erstellt haben

Eine gute Referenzdokumentation verwendet durchgängig den gleichen Stil. Manchmal ist bereits eine entsprechende Anleitung vorhanden, häufig müssen Sie diese Anleitungen zum Stil selbst entwickeln. Abbildung 2 zeigt einige allgemeine Anleitungen für die Kurzbeschreibungen.

Betrachten Sie zum Beispiel die Beschreibungen in Abbildung 3 für die Schaltflächenklasse in Microsoft .NET Framework. Dies ist ein Ausschnitt aus der SDK-Dokumentation auf MSDN.

Abbildung 2 Stil der Referenzdokumentation

Typ	Richtlinie	Beispiele
Klasse	Beginnen Sie mit einem Wort wie „Stellt dar“.	„Stellt das Fotoalbum eines Benutzers dar.“
Methoden und Funktionen	Beginnen Sie mit einem Verb	„Gibt die Anzahl der Kontakte für den angegebenen Bereich wieder.“ „Hält das Video an.“
Eigenschaften	Verwenden Sie ein Substantiv, oder beginnen Sie mit Verben wie „Ruft auf“ oder „Ruft auf und legt fest“.	„Die Aufgaben des Benutzers.“ „Ruft eine Sammlung der Aufgaben des Benutzers auf und legt diese fest.“
Ereignisse	Beginnen Sie mit einem Ausdruck wie „Aufgerufen wenn“ oder „Tritt ein, wenn“.	„Wird aufgerufen, wenn die Antwort des Servers empfangen wird.“
XML-Elemente	Verwenden Sie einen substantivischen Ausdruck.	„Die Postleitzahl des Orts“.
Boolesche Werte	Beginnen Sie bei Booleschen Eigenschaften mit „Zeigt an, ob“. Bei Booleschen Wiedergabewerten für Methoden und Funktionen beginnen Sie mit „Gibt zurück, ob“.	„Zeigt an, ob das Steuerelement sichtbar ist.“ „Zeigt an, ob es Überschneidungen zwischen zwei Bereichen gibt.“

Abbildung 3 Beispiel für eine Referenzdokumentation

Klasse oder Element	Typ	Beschreibung
Klassenbeschreibung	Klasse	Stellt eine Windows-Schaltfläche dar.
Schaltfläche Konstruktor	Konstruktor	Initialisiert eine neue Instanz der Klasse Schaltfläche.
Fokus	Methode	Legt den Eingabefokus für das Steuerelement fest.
Sichtbar	Eigenschaft	Ruft einen Wert auf, oder liegt diesen fest, der anzeigt, ob das Steuerelement und alle untergeordneten Steuerelemente angezeigt werden.
Klick	Ereignis	Tritt ein, wenn auf das Steuerelement geklickt wird.

Web-APIs

Die Anzahl der Web-APIs ist in den letzten Jahren stark gestiegen. Daher ist es die Mühe wert, sich zu überlegen, wie sich Web-APIs von lokalen APIs unterscheiden. Das Geschäftsmodell Software as a Service (SaaS) findet zunehmende Verbreitung, und Unternehmen stellen fest, dass die größeren Kunden die Dienste direkt auf ihren eigenen Systemen verwenden möchten. Das bedeutet, dass die Dienstanbieter eine öffentliche API bereitstellen müssen, die von ihren Kunden aufgerufen werden kann.

(Hinweis zur Terminologie: Ich verwende den Begriff „lokale API“, um die typische API zu beschreiben, die es bereits vor dem Internet gab. Technisch gesehen, kann es sich bei diesen APIs um Remoteprozeduraufrufe handeln, die in diesem Fall nicht lokal sind. Web-APIs können auf dem gleichen Computer aufrufen werden, der auch der Client ist, sodass sie in diesem Fall lokale APIs sind. In den meisten Fällen werden Web-APIs, die Standardprotokolle wie http verwenden, remote verwendet, während andere APIs lokal verwendet werden.)

Da die Web-APIs vergleichsweise neu sind, sind die entsprechenden Dokumentationen noch nicht standardisiert. Die Qualität der Web-API-Dokumentationen ist sehr unterschiedlich. Manchmal sind sie gut strukturiert und vollständig, manchmal enthalten sie nur die mindestens erforderlichen Informationen, die dann in einem Wiki gefunden werden. Wenn Sie eine Dokumentation für eine Web-API schreiben, sollten sie sich die Dokumentation ansehen, die andere Unternehmen für APIs veröffentlicht haben, um eine gute Vorlage zu finden, der Sie folgen können. Beispielsweise verfügt Twilio, eine Plattform für Sprach- und Nachrichtenanwendungen, über ein hervorragendes Beispiel für eine REST-Dokumentation, die Sie unter twilio.com/docs finden können. Hoffentlich einigt sich die Branche mit der Zeit auf eine kleine Anzahl von Vorlagen.

In gewisser Hinsicht sind Web-API-Dokumentationen wichtiger als Dokumentationen für lokale APIs, da es schwierig für Entwickler sein kann, Web-APIs zu testen, um mehr über deren Funktionsweise zu erfahren. Die Anzahl der Aufrufe, die Entwickler durchführen dürfen, kann beschränkt sein, oder die Tests haben Auswirkungen auf ein Livesystem, oder es kann schwierig sein, bestimmte Bedingungen zu emulieren, wenn z. B. der Server stark ausgelastet ist.

Wie bereits erwähnt, verlassen sich Entwickler in hohem Maß auf Beispielcode. Einer der wichtigsten Aspekte von Web-APIs ist deren Unabhängigkeit von Plattformen und Sprachen. Leider bedeutet dies zusätzlichen Aufwand für die Erstellung von Beispielcode. Sie müssen möglicherweise Beispielcode in Python, Ruby, Java, C# usw. erstellen. Versuchen Sie herauszufinden, welche Programmiersprachen Ihre Kunden am häufigsten verwenden, und konzentrieren Sie sich auf die wichtigsten Sprachen.

Die beiden am häufigsten für Web-APIs verwendeten Technologien sind SOAP und REST. SOAP hat ein Definitionsformat (Web Services Description Language, WSDL), das sich hervorragend als Ausgangspunkt für eine Referenzdokumentation eignet. REST verfügt nicht über ein Definitionsformat. Beispiel-http-Aufrufe und XML/JSON-Dateien sind für beide Technologien nützlich, um zu zeigen, wie sie funktionieren, reichen jedoch nicht aus. Den Beispielen sollten Tabellen folgen, die die einzelnen Elemente und deren Datenformat beschreiben.

Beispielsweise reicht es möglicherweise nicht, einen Parameter als eine Zeichenfolge zu beschreiben. Gibt es Sonderzeichen, die nicht verarbeitet werden können? Gibt es Längenbeschränkungen? Wenn es sich bei einem XML-Element um ein Datum handelt, sollten Sie das Format des Datums angeben. Wenn es sich um eine Uhrzeit handelt, müssen Sie die Zeitzone angeben.

Außerdem müssen Sie erklären, wie Fehler behandelt werden. Dies kann sich für die einzelnen Formate unterscheiden, die von der API unterstützt werden. Wenn die API HTTP-Antwortcodes für die Benachrichtigung über Fehler verwendet, sollten diese dokumentiert werden. Die Fehlerdokumentation sollte erklären, warum ein Fehler auftritt und wie das Problem behoben werden kann.

Für Web-APIs ist häufig eine Authentifizierung erforderlich. Diese muss ebenfalls detailliert beschrieben werden. Wenn Entwickler API-Schlüssel benötigen, stellen Sie Schritt-für-Schritt-Anleitungen dafür bereit, wie sie diese erhalten können. Denken Sie daran, dass Web-APIs auf HTTP aufbauen. HTTP ist ein äußerst funktionsreiches Protokoll. Möglicherweise gibt es HTTP-bezogene Informationen, die dokumentiert werden müssen, wie Caching, Inhaltstyp und Statuscodes.

Web-APIs sind so neu, dass wir uns noch in einer Phase befinden, in der die Art und Weise der Erstellung der Dokumentation noch in der Entwicklung ist. Sie können davon ausgehen, dass in den nächsten Jahren Standards für Web-API-Dokumentationen entwickelt werden.

Veröffentlichen

Bisher habe ich mich auf den Inhalt konzentriert. Sie müssen die Dokumentation jedoch auch veröffentlichen, sodass Entwickler diese lesen können. Im Allgemeinen erwarten Entwickler eine webbasierte Dokumentation, die Hyperlinks enthält, und nicht Formate wie z. B. PDF. Es gibt mehrere Möglichkeiten, eine Dokumentation im Web zu veröffentlichen.

Wenn die API klein ist, ist es wahrscheinlich am einfachsten, einfach HTML-Dateien zu erstellen. Mithilfe von CSS können Sie der Dokumentation ein Aussehen geben, das der Website Ihres Unternehmens entspricht.

Wikis stellen eine Struktur für komplexere APIs bereit. Wikis ermöglichen Ihnen auch die einfache Aktualisierung oder Ergänzung der Dokumentation, ohne dass Sie auf andere Tools oder Server zugreifen müssen. Außerdem ermöglichen die Teamarbeitfunktionen von Wikis ganzen Teams, zur Dokumentation beizutragen – sogar den Benutzern. Es ist jedoch keine wirklich brauchbare Strategie für die Erstellung einer API, ein Wiki zusammenzustellen und anschließend darauf zu hoffen, dass die Entwickler und Benutzer die Dokumentation schreiben.

Es gibt mehrere Open Source-Wikimodule, die zunehmend häufiger für API-Dokumentationen verwendet werden, wie das PHP-basierte MediaWiki (mediawiki.org/wiki/MediaWiki) und das PERL-basierte TWiki (twiki.org).

Kommerzielle Tools für Dokumentationen wie Madcap Flare (siehe madcapsoftware.com/products/flare) und Adobe RoboHelp (siehe adobe.com/products/robohelp) wurden primär für Endbenutzerdokumentationen entwickelt, können jedoch leicht für API-Dokumentationen angepasst werden. Sie stellen eine einfache Benutzeroberfläche für die Eingabe von Informationen bereit und ermöglichen ein besseres Layout als ein Wiki. Sie können aus der gleichen Quelle Webdateien und Textdateien generieren.

Dienste für die Onlinezusammenarbeit wie PBworks (pbworks.com) und MindTouch (mindtouch.com), werden ebenfalls zur Erstellung von API-Dokumentationen verwendet. Zusätzlich zu den Teamarbeitfunktionen von Wikis bieten diese Tools Funktionen wie Hosting, abgestufte Zugriffssteuerung und Skripting. Für die kommerzielle Nutzung dieser Services muss in der Regel eine Abonnementgebühr gezahlt werden.

Veröffentlichen Sie!

Eine gute API-Dokumentation ist für die Akzeptanz der Plattform und die Reduzierung der Anzahl der Supportanrufe wichtig. Wenn Sie Ihren Manager überzeugen können, einen technischen Autor mit den richtigen Fähigkeiten zu beauftragen, tun Sie es. Wenn Ihnen dies nicht gelingt, befolgen Sie die Hinweise in diesem Artikel.

Ihre Dokumentation sollte eine Übersicht enthalten, eine Hilfe für den Einstieg, Beispielcode und Referenzmaterial. Achten Sie darauf, dass Sie in der Übersicht erklären, warum die Plattform verwendet werden sollte. Stellen Sie Lernprogramme zusammen, um Entwicklern beim Einstieg zu helfen. Der Beispielcode sollte den Schwerpunkt auf Klarheit und Einfachheit legen, und muss nicht immer den Kodiergrundsätzen von Produktionscode folgen. Das Referenzmaterial sollte detailliert und konsistent sein. Es gibt eine Reihe von Tools, die Sie bei der Veröffentlichung der Dokumentation im Web unterstützen.

Erstellen Sie Ihre Dokumentation!

Peter Gruenbaum  ist ursprünglich Physiker und nun Software-Entwickler. Er beschäftigt sich mit Technologien aus so verschiedenen Bereichen wie Tablet-PCs, Augmented Reality, computergestütztes Design (Computer-Aided Design, CAD) und Operationssimulationen. Er gründete SDKBridge LLC, um seine Liebe zur Technologie und zum Schreiben von Texten zu verbinden, wo er nun zum Thema Technologie schreibt und unterrichtet.

Unser Dank gilt den folgenden technischen Experten für die Durchsicht dieses Artikels: John Musser (ProgrammableWeb) und Eugene Osovetsky (WebServius)