Linguistic Patterns and Antipatterns Detection and Their Impact on Understandability and Readability of APIs

Background Application programming interfaces (APIs) help distributed systems and microservices to expose their functionalities and serve as a means for communication among them. Understandability and readability of APIs are important for effectively comprehending and using APIs. Despite the presence of established API design rules and guidelines (i.e., design patterns), many poor design practices (i.e., antipatterns) are prevalent in APIs. APIs with high‐quality design are essential both for API providers and client developers. Goal This paper aims to (1) assess the linguistic design quality of APIs in distributed systems and microservices by automatically detecting antipatterns and design patterns in APIs and (2) evaluate the impact of linguistic patterns and antipatterns on the understandability and readability of APIs. Method We rely on syntactic and semantic analyses for automatic assessment of the design quality of APIs using detection heuristics. Syntactic analysis involves analyzing the structure and syntax of the APIs, while semantic analysis involves analyzing API documentation, descriptions, and parameters. We also conducted a survey and asked participants to determine the purpose of API snippets (comprehension task) and rate the difficulty in the understandability and readability of those API snippets. Findings We achieved an average accuracy of more than 94% in detecting patterns and antipatterns. Our detection results also suggest that antipatterns are prevalent in the APIs of distributed systems and microservices. Our survey findings revealed that adherence to linguistic patterns significantly enhances the understandability and readability of APIs. In contrast, linguistic antipatterns negatively affect the understandability and readability of Web APIs. Conclusion Our findings will assist API developers in identifying poor design practices and improving their APIs' design quality. Findings from our survey also highlight the importance of adhering to good API design practices to enhance the understandability and readability of APIs.