Dokumentation von RESTful-APIs
- Degree programme: BSc in Informatik
- Author: Sven Nyffenegger
- Thesis advisor: Dr. Michael Röthlin
- Expert: Dr. Igor Metz (GLUE Software Engineering AG)
- Year: 2015
Web APIs haben in den letzten Jahren zunehmend an Bedeutung gewonnen. Ein grosser Anteil der heute konzipierten Web APIs folgt dem REST-Paradigma (REpresentional State Transfer). Im Gegensatz zu dem aus der XML-Welt bekannten SOAP fehlen im Bereich RESTful-APIs allseits akzeptierte Standards und Werkzeuge für das Dokumentieren solcher Schnittstellen. Dies heisst aber nicht, dass es keine Standards gibt, sondern dass sich keiner der bestehenden bisher durchgesetzt hat.
Der Vergleich
In einem ersten Schritt wurden die drei verbreiteten Standards API Blueprint, Swagger und RAML analysiert und an einem Beispiel-Projekt angewendet. Hierzu wurden auch die entsprechenden Werkzeuge eingesetzt, die zum jeweiligen Standard angeboten werden. Es konnte festgestellt werden, dass sehr komfortable Lösungen zur Dokumentation von APIs existieren.
Anschliessend wurde eine Systematik zur Bewertung der Standards erarbeitet. Um eine möglichst realitätsgetreue Gewichtung der einzelnen Punkte zu erreichen, wurde diese zusammen mit einem Experten aufgestellt. Das Resultat, ein Raster zur Entscheidungsfindung, zeigt die Schwächen und Stärken der Standards auf.
Welcher Standard ist sinnvoll?
Der Vergleich hat gezeigt, dass die Standards verschiedene Ansätze verfolgen und für unterschiedliche Technologien ausgelegt sind.
Bei API Blueprint steht die Dokumentation am Anfang und im Zentrum, und soll in einem agilen Verfahren entwickelt werden. Um eine Diskussion mit involvierten Personen wie Projektleiter oder Kunden zu führen, setzt der Standard auf eine einfach zu lesende Markdown-Syntax.
Wird in einem bestehenden Java Projekt mit einer RESTful API eine Dokumentation eingeführt, sollte Swagger in Betracht gezogen werden, welcher die Integration mit Java optimal unterstützt. Die Dokumentation kann zur Laufzeit erzeugt werden und direkt mit weiteren Tools weiterverwendet werden, z. B. für die Erstellung von Unit Tests.
Die Spezifikation von RAML (RESTful API Modeling Language) bietet als einziger Standard eine vollständige Unterstützung von JSON- und XSD-Schemas an.
Fazit
Die Analyse hat gezeigt, dass nützliche Werkzeuge existieren, die sich je nach Anwendungsgebiet unterschiedlich eignen. Es sollte weiter berücksichtigt werden, dass momentan nur eine geringe Übertragbarkeit zwischen den Standards besteht. Da sich das Umfeld der Web APIs aber rasch weiter entwickelt, ist zu hoffen, dass sich ein Standard durchsetzt oder sich die Kompatibilität deutlich verbessert.
