Schnittstellenbeschreibungen 👍 👎

Vor Kurzem war ich damit beschäftigt, die Schnittstellen zweier externer Anbieter zu implementieren. Es handelte sich um eine REST- und eine SOAP-basierte Schnittstelle ähnlichen Umfangs, die per PHP angesprochen werden sollte. Dabei fielen mir jedoch erhebliche qualitative Unterschiede der Schnittstellenbeschreibungen auf.

Die REST-basierte Schnittstelle wurde wohl eher von der Marketing-Abteilung zur Bewerbung des Produktes geschrieben, als von Entwicklern für Entwickler. Nicht nur die technische Inkonsistenz, sondern vor allem auch der Schreibstil waren mehr verwirrend als hilfreich. Nicht zuletzt fehlten einige wesentliche Informationen zur Verwendung (u. a. Wertebereiche), die sich schließlich erst durch einige Versuche ergaben, die in diesem Fall zu allem Überfluss auch noch jeweils kostenpflichtig waren. Der relevante Abschnitt des Dokumentes belief sich auf etwa 25 Seiten, die man sich aber auch erst einmal zusammensuchen musste. Fehlermeldungen und Hinweise hätten an der ein oder anderen Stelle ebenfalls nicht geschadet.

Auf der anderen Seite war die Beschreibung der SOAP-Schnittstelle des anderen Dienstes mit unter 10 Seiten knapp gehalten. Die zur Verfügung stehenden Methoden und deren Parameter wurden ohne große Umschweife erwähnt und mit allen notwendigen Informationen beschrieben. So ergab es sich, dass der eigentlich als schnell implementierbar gedachte erste Dienst auf REST-Basis etwa 3-4 mal so lange zur Umsetzung bedurfte, als der als umfangreicher eingeschätzte SOAP-Dienst.

Insofern möchte ich gerne Anbieter von Webdiensten, die das hier evtl. lesen, dazu ermuntern, ihre Schnittstellenbeschreibung vor der offiziellen Veröffentlichung mit einem externen Entwickler im Rahmen einer vollständigen Implementierung durchzugehen, um derartige Schwachstellen schnell aufdecken zu können. Insbesondere sollte es auch immer eine Testumgebung geben, die sich nach Außen wie die eigentliche Schnittstelle verhält, jedoch keine Auswirkungen (insbesondere keine Kosten) verursacht.


Projektverweise

Kategorien / Archiv  |  Übersicht RSS-Feed

Schlagworte

Suche