Motivation

The Representational State Transfer (REST) architecture is, by far, the most popular approach to build Application Programming Interfaces (APIs) that expose Web services. Today, APIs.guru lists more than 2500 REST APIs: social networking, e-commerce, weather, and many more. However, developing and using a REST API is not a straightforward task. Over the lifetime of an API, stakeholders, including Product Owners (PO) and developers, collaborate to define 1) the “Requirements“, the business needs formulated by POs; 2) the “Code“, a formal representation of the API, articulating its concepts and logic by the API developers; and 3) the “Documentation“, a comprehensible description of the code for the API consumers (external developers).

Despite referring to the same REST API, stakeholders use heterogeneous terms and concepts that are semantically and syntactically different. This impreciseness is harmful as it leads to ambiguity, e.g., developers encounter difficulties in understanding business requirements when developing an API. It also causes misusages/misconfigurations impacting productivity. It is reported here that about 65.5% of endpoints have some form of inappropriate usage examples in Web API documentation.

This situation can lead to dramatic problems. Therefore, developing accurate and usable REST APIs requires coherence among the three facets we have identified: requirements, code, and documentation. The goal of the PEEPS project is to ensure this coherence, which we refer to as “Preciseness in REST APIs”, by raising the abstraction level for stakeholders and designing bridges between the three facets.

Challenges

PEEPS addresses three major problems developers face when developing large REST APIs (i.e., containing more than a million lines of code). Namely, the challenges are 1) the API code must conform to the API requirements, 2) the API documentation must conform to the API code, and 3) each time the API evolves, the documentation must co-evolve. The more complex the API, the more challenging its preciseness will be. 

Principal Activites

PEEPS project proposes the first model-driven framework for defining, maintaining, and evolving precise REST APIs. It contains four major tasks:

Task 1. Empirical studies for REST API preciseness. This task focuses on analyzing existing REST API code and their OpenAPI specifications. The objective is to establish a strong empirical foundation for the subsequent work packages.

Task2. Model-based REST APIs. We will first define a metamodel, based on an enhanced version of the OpenAPI standard. This metamodel will provide all the required concepts, their attributes, and associations to define REST APIs. Second, we will generate models that conform to the aforementioned metamodel of REST APIs, by leveraging API code and developer tests as primary sources of knowledge.

Task3. REST API conformance. This task will focus on the preciseness of REST APIs in terms of requirements, code, and documentation. This work package will first explore how business stakeholders, a.k.a. product owners (POs), can be included in ensuring the conformance of REST API code to business requirements. Second, it will tackle the generation of precise OpenAPI specifications to be exploited by API consumers. PEEPS will leverage a model-based approach combined with behavior-driven development.

Task4. Requirements, code and documentation co-evolution. PEEPS will split this task into three sub-tasks: the code-model co-evolution, the code-requirements co-evolution, and the code-documentation co-evolution.

ANR JCJC PEEPS project is funded by ANR, the French National Research Agency.