Konsequenzen von schlechtem API Design

Ein schlecht designtes API führt zu Mehraufwand auf Seiten der Entwickler, der Integratoren und Betreiber.

Autor:  Christian Ludt

Wird ein API schlecht designt, hat das weitreichende Konsequenzen: Wer es nutzt, benötigt zu viel Zeit, um es zu verstehen, zu viel Zeit, um es zu verwenden und macht zu viele Fehler. Mein Erfahrungsbericht aus dem Alltag zeigt auf, wie sich ein schlecht designtes API konkret auf das Projekt und den Betrieb auswirkt.

Nicht immer hat man selbst Kontrolle über das Design eines APIs. Wenn Produkte eines Dritt-Herstellers eingekauft werden, hat man selten direkten Einfluss auf die Entwicklung und das Design der Schnittstellen. Bei einem ipt-Kunden wurde ein Produkt eines Dritt-Herstellers angeschafft, das eine schlecht entworfene, REST-ähnliche Schnittstelle anbietet. Die folgenden vier Design-Fehler führten während der Entwicklung des Clients und während der Integration immer wieder zu Problemen.

Nicht-Validierbarkeit

Der Inhalt des entscheidenden Requests sind zwar strukturierte Daten. Aber sie sind – entgegen der mehrfach in der Dokumentation erwähnten Aussage – nicht gegen ein XML-Schema validierbar. Der Content-Type ist plain/text und der Inhalt ein sehr komplexes, XML-artiges Gebilde. Der Dritt-Hersteller bietet dafür kein SDK oder sonstige Tool-Unterstützung an.

Ohne eine formale Beschreibung – wie zum Beispiel ein XSD- oder JSON-Schema – ist es nicht möglich, Requests auf Korrektheit zu prüfen. Fehler werden dadurch erst zur Laufzeit erkannt. So ist langwieriges Fehlersuchen vorprogrammiert, die Entwicklung und Integration verzögern sich, und das Projekt gerät in Verzug.

Schlechte, keine oder falsche Fehlermeldungen

Wird der oben genannte Request nun mit einem fehlerhaften Inhalt gesendet, so dass der Server den Inhalt nicht versteht, liefert der Server eine allgemeine Fehlermeldung: HTTP 500 – Internal Server Error. Für den Client ist es dadurch nicht ersichtlich, dass er einen fehlerhaften Request gesendet hat. Der Server sollte hier besser ein HTTP 400 – Bad Request schicken, um dem Client mitzuteilen, dass hier ein Fehler auf Seite des Clients vorliegt. Zusätzlich hilfreich wäre in diesem Fall eine Angabe, wo genau der Fehler liegt.

Schlechte, keine oder falsche Fehlermeldungen haben Auswirkungen sowohl auf die Entwicklung und Integration als auch auf den Betrieb. Wenn niemand weiss, wo genau der Fehler liegt, sind im besten Fall alle Parteien beteiligt, den Fehler zu finden. Im schlechtesten Fall wird sich niemand darum kümmern.

Fehlerhafte Dokumentation

Von Menschenhand erstellte Dokumentation kann fehlerhaft sein. Mühsam wird es, wenn aus der Dokumentation herauskopierte Beispiel-Requests nicht funktionieren. Entwickler suchen in der Regel den Fehler zunächst einmal bei sich selbst und überprüfen jedes Bit und Byte, sei es der vielleicht falsch gesetzten Content-Type, falsches Encoding oder vergessene HTTP Header.

Meist kommt der Gedanke an falsche Beispiel-Requests erst ganz zum Schluss; bis dahin sind oft schon mehrere Stunden vergangen, bei komplexen Requests vielleicht sogar mehrere Tage.

Keine Abwärtskompatibilität

In einem Minor-Release wurde die Implementierung an die Dokumentation angepasst, anstatt die Dokumentation an die Implementierung anzupassen. Dadurch war die Schnittstelle mit der vorherigen Version nicht mehr kompatibel. Dies hatte zur Folge, dass alle Clients angepasst werden mussten.

Dieser API-Design-Fehler gehört sicher zu denjenigen, welche sich am Einfachsten vermeiden lassen.

Fazit

Ein schlecht designtes API führt zu Mehraufwand auf Seiten der Entwickler, der Integratoren und Betreiber. Wenn man ein API nicht selbst unter Kontrolle hat, bleibt einem nichts anderes übrig, als damit zu leben. Dies muss von Anfang an bei der Planung berücksichtigt und der unvermeidbare Mehraufwand mit einkalkuliert werden. Dann wird auch die Integration eines schlecht designten APIs zum Erfolg.