Discovering, composing, generating and testing REST APIs with OpenAPI and OData

Web APIs have increasingly becoming a key asset for businesses, thus boosting their implementation and integration in companies’ daily activities. Such importance is reflected by the growing number of available public Web APIs, listed in a number of catalogs (e.g., apis.guru with more than 800 APIs or programmableweb with more 19000 APIs).

In practice, most of these Web APIs are, at most, “REST-like”, meaning that they adhere partially to the Representational State Transfer (REST) architectural style. REST is a technical description which outlines the principles, properties, and constraints to build Internet-scale distributed hypermedia systems. Indeed, REST is a design paradigm and does not propose any concrete reference underlying technology or standard. Thus, both developing and consuming REST APIs are challenging and time-consuming tasks for API providers and clients, respectively.

Indeed, API providers should have a sound API strategy fostering ease of use while respecting REST constraints. On the other hand, API consumers are having a hard time integrating Web APIs to their applications due to the lack of machine-readable definitions. Web APIs are typically described using textual descriptions even if several initiatives for providing a more “machine-readable” API description exist. Recently, and aiming at standardizing the way to describe REST APIs, a consortium of major actors in the API market has launched the OpenAPI Initiative (OAI). This initiative has the objective of creating a vendor-neutral, portable, and open specification for describing REST APIs. OAI has succeeded in attracting major companies and the OpenAPI specification has become the choice of reference to describe REST APIs. On the other hand, Open Data Protocol (OData), is an emerging specification for Web APIs which is specially useful to expose and query data sources as REST APIs. The current version of OData (version 4.0) has been approved as an OASIS standard.

Despite these unification efforts, a number of open challenges to consume and publish web APIs remain:

• Many webs do not offer an API. We need the “APIfication” of existing web resources.
• Many REST APIs do not yet include an OpenAPI specification (or any other similar initiative) to describe themselves. Therefore the API behavior and data must be discovered
• Many of the OpenAPI descriptions are inconsistent with the actual API. APIs must be tested.
• To be useful, many apps require merging data coming from different APIs. APIs must be easily composed.

Yesterday, Hamza Ed-douibi successfully defended a PhD Thesis that addresses these issues. The goal of his thesis is to facilitate the design, implementation, composition and consumption of REST APIs, targeting specially the OpenAPI specification and OData protocol, by relying on Model-Driven Engineering (MDE). As the readers of this website already know, MDE is a methodology that promotes the use of models and transformations to raise the level of abstraction and automation in software development, respectively. The thesis took place in the context of our ongoing project Open data for all: an API-based approach.

This thesis proposes the following core contributions:

1. APIDiscoverer, an example-based approach to automatically infer OpenAPI specifications for REST APIs, thus helping developers increase the exposure of their APIs without fully writing API specifications;
2. APITester, an approach to generate test cases for REST APIs relying on their OpenAPI specifications to assess that the behavior of an API conforms to its specification;
3. APIGenerator, a model-driven approach to automate the generation of ready-to-deploy OData REST APIs from data models; and
4. APIComposer, a lightweight model-based approach to automatically compose REST APIs based on their data models.

In the context of this thesis, we have also developed a number of other complementary results and tools, like OpenAPItoUML (to visualize OpenAPI definitions in UML) or EMF-Rest a way to access and manage software models themselves via a REST API.

These contributions constitute an ecosystem to advance the state of the art in automated software engineering for REST APIs development and consumption. We believe such contributions to be of a great value to Web APIs developers who want to bring more agility to their development tasks. Feel free to read the full thesis manuscript, take a look at the defense presentation slides below or just get in touch for more info on any of these tools!.