Linguistic Qualtiy Detection of APIs

SE+AI Research Lab, FCS, University of New Brunswick
Explore the project »

View Demo · CASCON Article

About The Project

Background: APIs or Application Programming Interfaces 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 (or design patterns), poor design practices (or antipatterns) are still 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 conduct a survey and ask participants to answer the purpose of the API snippets (comprehension task) and rate the difficulty in understandability and readability of the 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. The findings of our survey revealed adherence to linguistic patterns significantly enhances the understandability and readability of APIs. In contrast, linguistic antipatterns have negative effects on the understandability and readability of Web APIs.

Conclusion: Our findings will assist API developers in identifying poor design practices and improving the design quality of their APIs. Findings from our survey also highlight the importance of adhering to good API design practices to enhance the understandability and readability of APIs.

(back to top)

Methodology

Linguistic Patterns

Linguistic patterns and antipatterns studied in this are availabele here . Additionally, the detailed detection reuslt, analysis, and findings can be accessed here .

Impact Survey

The impact survey, which assesses the effects of linguistic patterns and antipatterns on API understandability and readability, is available for review here . Additionally, the collected survey data and detailed analysis, including statistical insights and findings, can be accessed here .

Built With

• Python
• WorNet
• LDA Topic Model
• NLTK
• SPacy
• SPacy Similarity (Cosine)
• Inflect

(back to top)

Getting Started

This is an example of how you may give instructions on setting up your project locally. To get a local copy up and running follow these simple example steps.

Prerequisites

1. Python 3.6 or higher
2. R and R Studio

Installation

1. Clone the repo

   git clone [url] 

2. Downloads

   npm install [url]

3. Install all the libraires

   pip install nltk
   pip install spacy
   pip install gensim
   pip install inflect
   pip install sklearn

4. Required downloads

   nltk.download('wordnet')
   nltk.download('stopwords')
   nltk.download('punkt')
   nltk.download('omw-1.4')

5. Run the python script

   python3 test.py
   python run_all.py

6. Run the R script

   survey-analysis.R

File Structure

API-Quality/
├── REST/
│   ├── APIs
│   │   ├── API_Name.txt
├── GraphQL/
│   ├── APIs
│   │   ├── API_Name.txt
├── All-Data/
│   ├── output_data.jsonl
│   ├── result_summary.csv
├── Journal Resources/
│   ├── Images/
│   │   ├── Detection/
│   │       ├── {image}.pdf
│   │   ├── Impact/
│   │       ├── {image}.pdf
│   ├── Detection-Result/
│   │    ├── Validation Result.xlsx
│   │    ├── RQ Analysis.xlsx
│   │    ├── result_summary.csv
│   ├── Impact-Survey/
│   │    ├── results-survey.csv
│   │    ├── survey-analysis.R
│   │    ├── Impact-Survey-Design.pdf
│   │    ├── patterns.yaml
│   │    ├── antipatterns.yaml
│   │    ├── data-cleaning-protocol.md
│   │    ├── dataset-description.md
│   ├── api_analyzer.py
│   ├── data-count.py
│   ├── display_options.py
│   ├── file_handler.py
│   ├── result_summary.py
│   ├── run-all.py
│   ├── test.py
│   ├── uri_cleaning.py
│   ├── acronyms.txt

License and Copyright

Copyright (c) 2025 [SE+AI Lab]

Permission is granted to use, copy, modify, and distribute this project with credit to SE+AI Lab.

THE PROJECT IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND.

Contact

SE+AI Lab

(back to top)