A framework for the definition of precise REST APIs

The Representational State Transfer (REST) architectural style is, by far, the most popular approach to building Application Programming Interfaces (APIs) that expose Web services. Today, APIs.guru documents more than 2500 publicly available REST APIs, including social networking APIs, e-commerce APIs, weather APIs, 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, that is, the business needs formulated by POs; 2) the Code, that is, a formal representation of the API specifying its concepts and logic by the API developers; and 3) the Documentation, a comprehensible description of the code for the API consumers (i.e., 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. REST API consumers might use incorrect HTTP headers or data types due to the impreciseness of the textual documentation or due to the evolution of the API, which leads to outdated documentation [1]. It is reported that about 65.5% of endpoints have some form of inappropriate usage examples in Web API documentation [2]. 

Developing accurate and usable REST APIs requires coherence in API development. The goal of this doctoral thesis is to ensure coherency between the three facets (requirements, code, and documentation) of REST APIs by raising the abstraction level for stakeholders and by designing bridges that ensure coherency and conformance between the three facets. We call this preciseness.

Objectives of this doctorate

The objectives for this project are formulated as the following research questions:

RQ1: How do we provide REST APIs that conform to the requirements?

RQ2: How do we enrich REST API documentation?

RQ3: How do we ensure and verify the automatic co-evolution between the requirements, the code and the documentation?

First, we will empirically investigate the coherency of the three facets (requirements, code, and documentation) of REST APIs, and how they evolve and diverge in practice. We will rely on existing API Hubs, in particular APIs.guru and RapidAPI, as well as code hosting platforms, in particular GitHub and Software Heritage. Second, we want to allow non-developers to write their business requirements and execute them as conformance tests on the REST API (RQ1). These tests will verify the conformance of the API code to the business requirements and guide the developers in the process of implementing their API. Third, we will generate complete and accurate model-based specifications to enhance the preciseness of REST APIs, by adding metadata and constraints to the specifications (RQ2). We will leverage the API code and developers' tests for the generation of the OpenAPI descriptors. Fourth, we will co-evolve non-generated parts of the documentation (e.g., parameter constraints, endpoint access rights) with the evolving API, in the context of agility, continuous integration, and DevOps practices (RQ3). We’ll rely on machine learning resolutions to identify the changes and perform the co-evolution.

Skills 

• Master’s degree in computer science or a closely related field
• Knowledge in Web Development, OpenAPI and/or Model-Driven Engineering (MDE)
• Good programming skills
• Ability to work autonomously
• Willingness to learn about new technologies/techniques
• Good writing and communication skills
• Ability to propose, present, and discuss new ideas

The doctoral candidate will learn to do top-quality research and publish in top-level venues, such as ICSE, MODELS, ASE and the WebConf. Furthermore, they will develop their skills in Web programming, Javascript, Model-Driven Engineering, Linux, Docker, Git, among many other technologies.

As is a common practice in the DiverSE research team, all source code will be open-sourced using either the GPL or Apache Licenses. It is expected that the doctoral student participate in related open-source communities. This should also assist in the technological transfer from academic prototypes to industrial-ready tools. Experimentations to demonstrate the effectiveness of developed tools on real-world issues are actively encouraged and expected.