Description languages for REST APIs - state of the art, comparison, and transformation

Abstract

In recent years, the architectural style for building Web Services called "Representational State Transfer" (REST) gained a lot of popularity in industry and academia. Since designing complex, distributed hypermedia systems still meeting all the REST constraints is a difficult task, an academic, model-driven approach based on a multi-layered metamodel was developed in order to enforce REST compliance. Apart from that, multiple REST API description languages emerged in industry, providing means to formally define the structure of an API for human (e.g. API documentation) and machine (e.g. automated creation of client/server stubs) consumption. This work aims to compare the academic metamodel with API description languages widely used in industry. As a comparison methodology, bidirectional model transformations were designed and implemented between the academic metamodel and each of the two leading API description languages, Swagger and RAML. The model transformations were evaluated with a quantitative method by applying them on real world API descriptions as well as manually evaluating the quality of the transformed models. The model transformations show that indeed various mappings can be established between model elements of different metamodels. However, there are also crucial differences which are also examined in this thesis.

In den letzten Jahren erlangte der Architekturstil namens "Representational State Transfer" (REST) zur Entwicklung von Web Services eine hohe Popularität in Industrie und Forschung. Aufgrund der Tatsache, dass der Entwurf von komplexen, verteilten Hypermedia Systemen, die dennoch alle Bedingungen von REST genügen, eine schwierige Aufgabe ist, wurde ein forschungsorientierter, modellgetriebener, auf mehrschichtigen Metamodellen basierender Ansatz entwickelt, um die Einhaltung der REST Vorgaben sicherzustellen. Unabhängig davon entstanden in der Industrie mehrere Beschreibungssprachen für REST APIs, wodurch deren Struktur formal beschrieben werden kann, sodass sie von Mensch (z.B. für die API Dokumentation) und Maschine (z.B. zur automatischen Generierung von Client/Server Code-Skeletten) genutzt werden kann. Die vorliegende Arbeit vergleicht das forschungsorientierte Metamodell mit API Beschreibungssprachen, die in der Industrie häufig verwendet werden. Als Vergleichsmethode wurden bidirektionale Modelltransformationen zwischen dem Forschungsmodell und je eine der beiden führenden API Beschreibungssprachen Swagger und RAML entworfen und implementiert. Die Transformationen wurden sowohl quantitativ evaluiert, indem sie auf eine Vielzahl von existierenden, realen API Beschreibungsdokumenten angewandt wurden, als auch qualitativ durch eine manuelle Evaluation der Qualität der generierten Beschreibungen. Die Modelltransformationen zeigen, dass in der Tat einige semantische Abbildungen von Modellelementen unterschiedlicher Metamodelle hergestellt werden können. Allerdings gibt es auch wesentliche Unterschiede, die ebenso in dieser Thesis untersucht werden.