DOLAR: Auditing the Linguistic Health of Modern RESTful APIs

TL;DR

Even tech giants like Facebook and Twitter struggle with consistent API naming. This paper presents DOLAR, an automated auditing tool that uses Natural Language Processing (NLP) to detect "Linguistic Antipatterns"—poor naming choices that make APIs harder to use. While most designers successfully avoid using verbs in URIs, a staggering 71% of analyzed endpoints suffer from syntactic clutter (Amorphous URIs).

The "Language" of Resources

In the world of REST, the URI is the primary interface. If a URI is titled /newspaper/player, a developer might be confused: are we talking about a media player or a football player? This lack of semantic harmony is a Contextless Resource Name antipattern.

The authors argue that software quality isn't just about functional correctness; it's about understandability. If the source code lexicon is messy, the API's reusability plummets. Existing tools were built for Java classes or SOAP services, but REST—with its focus on resources and HTTP verbs—needed a custom linguistic auditor.

Methodology: How DOLAR "Reads" an API

DOLAR doesn't just look for typos. It performs a deep dive into the relationship between nodes in a URI string using a three-step workflow:

1. Syntactic Analysis: Checking for lower-case consistency, underscores, and file extensions (e.g., avoiding .jpg in a URI).
2. Semantic Analysis: Utilizing WordNet to see if words like "University" and "Professor" share a hierarchical or contextual link.
3. Dynamic Invocation: Using the SOFA framework to actually call the API and inspect the real URIs generated at runtime.

Figure 1: The algorithmic rule for detecting Contextless Resource Names. It captures "Synsets" (synonym sets) for each URI node and checks if they overlap.

Key Findings: The Good, The Bad, and The Amorphous

The researchers tested DOLAR against 15 prestigious APIs (including YouTube, Instagram, and Dropbox). The results were eye-opening:

• The Good News: 93% of APIs correctly use Verbless URIs. Developers have finally learned that POST /deleteUser is a "CRUDy" mistake and should simply be DELETE /user.
• The Bad News: Amorphous URIs are everywhere. 71% of APIs use underscores, trailing slashes, or uppercase letters that violate RFC 3986 standards.
• The Structural Gap: Over half (55%) of the APIs showed Non-hierarchical Nodes, indicating that the logical "tree" of resources is often broken in practice.

Figure 2: Mosaic plot illustrating the prevalence of patterns (green) vs. antipatterns (red) across the 15 subjects. Note the dominance of Verbless URIs (Good) vs. Amorphous URIs (Bad).

Critical Insight: The Limitation of Dictionaries

The study highlights a fascinating challenge in Academic NLP: Domain Specificity. DOLAR initially flagged Facebook's /Canucks/albums as contextless because a general English dictionary (WordNet) doesn't know that "Canucks" is a sports team. This suggests that future API auditors must move beyond static dictionaries and toward Domain-Specific Ontologies or Large Language Models that understand "tech-speak" and pop culture.

Conclusion

DOLAR proves that we can automatically quantify the "beauty" and "logic" of an API's design. For API providers, this tool offers a path toward better developer experiences. For researchers, it opens the door to using more advanced NLP techniques to ensure that as our systems grow more complex, they remain human-readable.

Takeaway for Architects: Keep your URIs tidy, stick to nouns, and always ensure your URI nodes share a clear logical hierarchy. Your fellow developers will thank you.