Bad API Wording, Timed: UNB Put 108 Developers on a Clock and Measured the Confusion

Here is an endpoint in the wild: /Available-Data-Feeds/ — capital letters, a trailing slash, no version. Nothing about it tells a developer what it does, and everything about it has to be guessed before a single line of client code can be written. A team at the University of New Brunswick has now counted how much that guessing costs — in seconds, and in wrong answers.

In a study published October 23 in Software: Practice and Experience, Krishno Dey, Stuart Thiel and Francis Palma of UNB's SE+AI Lab, with Hung Cao of the Analytics Everywhere Lab, did three things: defined a field guide of 14 linguistic design patterns and their evil twins, built software to detect them, and ran both over 4,027 endpoints from 69 real REST and GraphQL APIs. Then they put 108 developers on a clock to find out whether any of it actually matters. It does, measurably.

A field guide to bad wording

The catalogue pairs every good habit with the antipattern that breaks it, and the examples are drawn from real APIs:

• ✗ Amorphous vs. ✓ Tidy. /Available-Data-Feeds/ is amorphous — uppercase, trailing slash. Its tidy twin, /available-data-feeds/{dataSourceId}, is lowercase, structured, and readable at a glance.
• ✗ CRUDy vs. ✓ Verbless. update/players/{id} stuffs a verb into the path, doing the HTTP method's job twice. The verbless /players/id lets the method speak.
• ✗ Contextless vs. ✓ Contextualized. /newspapers/earth/players/{id} throws unrelated nouns into one path; /football/club/players/{id} keeps every node in one world.
• ✗ Inconsistent Documentation. In Adobe's Audience Manager API, a POST to /datasources/bulk-delete is documented as "Bulk delete multiple data sources" — the method says create, the words say delete. Pipefy's POST /createCardRelation, documented "Creates a card relation," is the counterexample.

Ten of the 14 pairs come from the literature; four — including Parameters Tunneling and Identifier Ambiguity — are this team's own. PokéAPI, of all things, supplies documentation that has nothing to do with its endpoint.

What 4,027 endpoints actually look like

The detectors — syntactic checks on path structure, semantic checks on documentation — scored 94.07 per cent average accuracy against a ground truth set by three professionals. What they found is a split verdict. Most endpoints follow most of the rules: 98 per cent use contextualized resource names, 99 per cent are structured. But the failures cluster exactly where they hurt most:

• 74 per cent of the REST endpoints carry no version at all — the study's most common antipattern. Any change an unversioned endpoint's owner ships can break every client, silently. In GraphQL APIs the figure is 58 per cent.
• The antipatterns are not evenly spread. Pinterest's API shows a significant presence of them — inconsistent documentation, nonstandard and unversioned endpoints, CRUDy paths. Apple Music, Artsy, GitLab and IBM's Anomaly Detection API largely adhere to the patterns. And these 69 were chosen for being well-structured and documented — the wider world is likely worse.

Then they put developers on a clock

The detection half of the paper could be dismissed as automated tidiness. The experiment cannot. The team recruited 108 participants — students and professionals, all with at least basic Web API experience — and gave each of them 28 endpoint tasks presented as OpenAPI documents, half patterned, half antipatterned, in random order. For every task: say what it does. Correctness and time were fused into a single score (TAU, Timed Actual Understandability). Every one of the 14 pairs came out statistically significant after correction for multiple comparisons. The gaps are not subtle:

• Documentation that matches its endpoint: 84 per cent of participants got it right. Documentation that doesn't: 18 per cent.
• Contextless names: a contextualized path took 23 seconds on average; its contextless twin took 67 seconds — nearly triple, for the same operation.
• Unlabelled identifiers: 20.6 seconds with annotation, 49.5 seconds without.

And seniority is no shield. Experience helped on the well-worded tasks but did nothing on the antipattern ones: knowing the rules tells you something is wrong, not what the endpoint does.

The sceptical footnotes, and the bill

The caveats belong in the open. The ground truth behind that 94.07 per cent is 94 endpoints judged by three professionals — a sample, with majority voting where they disagreed. The experiment ran online, on snippets rather than production systems, with durations outside 5 seconds to 4 minutes discarded. And the long tail of undocumented internal APIs — the ones developers actually curse at — is uncounted entirely.

What survives the caveats is the shape of the result: the cost of bad wording is not a matter of taste, it is timed and counted, it falls on every developer who integrates with the API, not the team that wrote it, and the tooling to find it before it ships now exists — the team has published its data and materials on GitHub. The work was funded by the New Brunswick Innovation Foundation (award TRF2023-003) and UNB's Faculty of Computer Science. If a machine can grade your API's wording with 94 per cent accuracy, the argument in the next design review is no longer about preference. It is about who pays the 44 extra seconds, multiplied by every developer, every time.

Sources

• Dey, K., Thiel, S., Cao, H., Palma, F., "Linguistic Patterns and Antipatterns Detection and Their Impact on Understandability and Readability of APIs," Software: Practice and Experience, October 23, 2026: https://doi.org/10.1002/spe.70118 (open access, CC BY-NC-ND) — catalogue definitions and endpoint examples (Section 4), detection results (RQ1), impact experiment and Table A1 statistics (RQ2), threats to validity (Section 8)
• Study data as reported in the paper: 4,027 endpoints from 69 REST and GraphQL APIs; 74% of REST endpoints unversioned; detection accuracy 94.07%, precision 82.77%, recall 87.35%, F1 88.06%; experiment with 108 participants and 28 snippets; Pertinent Documentation correctness 84% vs 18%; Contextualized Resource Names 23.1s vs 66.8s mean comprehension time
• Replication package and study data, SE+AI Lab (UNB): https://github.com/krishnodey/API-Quality
• Funding as stated in the paper: New Brunswick Innovation Foundation, NBIF TRF award TRF2023-003, and the Faculty of Computer Science, University of New Brunswick