API-Dokumentation

Für die Nutzung einer API ist eine API-Dokumentation zwingend erforderlich.

Für die generelle Nutzung einer API siehe auch Styleguide:Techn. Integration via API

Anforderungen an die Dokumentation

Eine API-Dokumentation muss folgende Punkte umfassen:

• Es ist ein deutscher oder englischer Sprache verfasstes Dokument
• Das Dokument verfügt über ein Änderungsdatum
• Das Dokument definiert einen Ansprechpartner
• Die API verfügt über eine Versionsnummer
• Die generelle API-Methode muss erläutert sein (REST, XMLRPC, SOAP, etc.)
• Für jede API-Methode existiert eine Definition
  • API-Parameter werden mit ihrem erwarteten Wertebereich definiert. Dies kann einfach ein String, Integer, etc. sein, oder aber eine Liste von erlaubten Werten.
  • Bezieht sich ein API-Parameter auf einen dynamischen Wert (z.B. IDs etc.), so muss dies erläutert sein.
  • Authentifizierungsmechanismen müssen klar erläutert werden
  • Das Antwortformat muss klar definiert sein (z.B. JSON, XML, etc.)
  • Die Struktur der Antwort muss klar definiert sein. Dies beinhaltet eine Liste möglicher Werte für jedes Antwortfeld
  • Das Verhalten im Fehlerfall muss dokumentiert sein

Optional kann die Dokumentation umfassen:

• Das Dokument ist via HTTP abrufbar (HTML, PDF, ...)
• Für einzelne Methoden oder APIs insgesamt wird eine Caching-Zeit definiert
• Es existieren funktionierende Beispiele

Inhaltliche Anforderungen

Folgende inhaltliche Anforderungen müssen erfüllt sein:

• Für API-Antworten auf Suchen muss eine Sortierung der Suchergebnisse möglich sein
• Für API-Antworten auf Suchen muss eine quantitative Einschränkung der Suche möglich sein, um Effekte wie Blättern und das Begrenzen der Anzeige zu erlauben (vgl. MySQL: "LIMIT")

Für APIs, die dem Nutzer eine Buchung erlauben:

• Da BO / Berlin.de aus Sicherheitsgründen keine eigenen Buchungen durchführen kann, muss in der API-Dokumentation dokumentiert sein, wie für den finalen Buchungsschritt auf den API-Anbieter verlinkt werden kann

Beispiele

• https://dev.twitter.com/docs/api
• http://support.berlin.de/doc/php/files/simple/simple_search-api-php.html

Keywords: Anleitung