API-Dokumentation

Aus Imperia Support Wiki

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

Keywords: Anleitung