Preciseness in REST APIs definition – PEEPS

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 counts more than 2500 REST APIs, from social networking, to e-commerce or weather. However, developing and using a REST API is not a straightforward task. During API development, 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, i.e., developers encounter difficulties understanding business requirements when developing a Web 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. It is reported that about 65.5% of endpoints have some form of inappropriate usage examples in Web API documentation. This situation can lead to dramatic security problems. In fact, misconfigured Web APIs make up two-thirds of cloud breaches. Therefore, developing accurate, usable, and secure REST APIs requires coherence among the three facets I have identified: requirements, code, and documentation. The goal of the PEEPS project is to ensure this coherence, which I refer to as ”Preciseness in REST APIs”, by raising the abstraction level for stakeholders and designing bridges between the three facets.