Investigating the Linguistic Design Quality of Public, Partner, and Private REST APIs

Application Programming Interfaces (APIs) define how Web services, middle-wares, frameworks, and libraries communicate with their clients. An API that conforms to REpresentational State Transfer (REST) design principles is known as REST API. At present, it is an industry-standard for interaction among Web services. There exist mainly three categories of APIs: public, partner, and private. Public APIs are designed for external consumers, whereas partner APIs are designed aiming at organizational partners. In contrast, private APIs are designed solely for internal use. The API quality matters regardless of their category and intended consumers. To assess the (linguistic) design of APIs, researchers defined linguistic patterns (i.e., best API design practices) and linguistic antipatterns (i.e., poor API design practices.) APIs that follow linguistic patterns are easy to understand, use, and maintain. In this study, we analyze and compare the design quality of public, partner, and private APIs. More specifically, we made a large survey by analyzing and performing the detection of nine linguistic patterns and their corresponding antipatterns on more than 2,500 end-points from 37 APIs. Our results suggest that (1) public, partner, and private APIs lack quality linguistic design, (2) among the three API categories, private APIs lack linguistic design the most, and (3) end-points are amorphous, contextless, and non-descriptive in partner APIs. End-points have contextless design and poor documentation regardless of the API categories.