Die Anbindung an APIs hat teilweise erheblich von einander abweichende Aufwände. Was sind die Warnzeichen, dass der Aufwand für eine Schnittstelle deutlich höher werden kann?

Probleme und Stolpersteine beim Einbinden von Schnittstellen kann man im Vorfeld zumeist schon erahnen. Jede gute Schnittstelle verfügt über drei Qualitätsmerkmale:

  1. Dokumentation (siehe unten),
  2. Stabilität in der Definition (d.h. z.B. keine Weiterentwicklung während der Implementation),
  3. und eine Möglichkeit, die Schnittstelle zu testen.

Im Idealfall existiert auch noch ein Ansprechpartner. Wenn eine Schnittstelle keine Dokumentation besitzt, muss sie über einen Ansprechpartner verfügen. Die Aussage „Die Schnittstelle ist selbstdokumentierend“ ist übrigens ein Warnsignal, dass Probleme und Aufwände zu erwarten sind.

Dokumentation

Im Vorfeld sind folgende Fragen in Bezug auf eine Schnittstellen-Dokumentation wichtig:

  1. Entspricht die Schnittstelle einer bereits hinlänglich definierten Schnittstelle, z.B. RSS, ATOM, etc.? Wo weicht sie vom Standard ab?
  2. Ist die Dokumentation aktuell? Entspricht die Dokumentation dem tatsächlichen Zustand?

Die Dokumentation muss dann folgende Fragen beantworten:

  1. Wie sieht die Erreichbarkeit & Authentifikation der API aus? Gibt es spezielle Zugangshürden? Gibt es spezielle Transportprotokolle?
  2. Welche Methoden stehen zur Verfügung? Wie sehen die Parameter eine Anfrage aus, wie der Rückgabewert? Werden Typen für die einzelnen Parameter genannt? Gibt es Vorgabewerte? Welche Werte sind optional?
  3. Welche Fehlermeldungen kann es geben?
  4. Sollen Fehler-Logs für den jeweiligen Schnittstellen-Partner abgelegt werden?

Für jede Entitätentyp einzeln zu beantwortende Fragen:

  1. Gibt es Beispiele für Anfragen und Antworten?
  2. Wann muss eine Entität eingelesen / gesendet werden? Bei einer bestimmten Aktion, in einem bestimmten Turnus? Ist die Verarbeitung synchron oder asynchron?
  3. Wie soll das Mapping in die eigene Applikation aussehen? Welches Feld in der Quelle entspricht welchem Feld im Empfänger? Gibt es Fallbacks? Sind Felder obligatorisch?
  4. Gibt es irgendwelche magischen Konstanten, z.B. Schlüsseltabellen? Gibt es Abhängigkeiten zu anderen Ressourcen?
  5. Wie werden Löschungen übergeben?

Ein fantastisches Beispiel für eine REST-API-Dokumentation existiert bei der Twitter API-Dokumentation.

Und wenn eine API noch keine Dokumentation hat, kann man mittels Swagger eine schön saubere und gleichzeitig testbare Dokumentation aufbauen.


Andere Artikel zum Thema · · ·

Zuletzt geändert am

fboës - Der Blog