fboës - Der Blog

Wie hoch ist der Aufwand bei der Einbindung von Schnittstellen?

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. Gibt es Beispiele für Anfragen und Antworten?
  4. Welche Fehlermeldungen kann es geben?
  5. Gibt es irgendwelche magischen Konstanten, z.B. Schlüsseltabellen?

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.

Zur Übersichtsseite