In a recent edition of my newsletter, Net API Notes, I finished with an off-the-cuff remark about hating how one term was used interchangeably for another. If I said chaos ensued, I would be making a gross overstatement. However, it was, despite the numerous pointed and carefully crafted statements that I make on an ongoing basis, the thing that people responded to the most to in a long time.
Ludwig Wittgenstein was an Austrian-British philosopher. His is, perhaps, most famous for inspiring the phrase “language is use”. To explain what that means, here is a snippet from everyone’s favorite technical companion, Existential Comics, explaining why a hot dog is not a sandwich.
As the comic explains, we can pick apart the semantics of a term any of a thousand ways. We can debate the taxonomy, history, and context. We can make inferences and wring our hands over future outcomes, both seen and unseen. And, as Wittgenstein argued, all of that is irrelevant if it isn’t how people use the language.
In my time doing API governance, I’ve seen thousands of what I’ve come to call “API descriptions”. I use this term to disambiguate between many things that get mushed together. If a team says they “need help with their API,” they could be referring to:
- the code that implements some business functionality, exposed through a standardized interface (usually over HTTP)
- an endpoint (the unique combination of URI and method [as wrong as it is to refer to a single endpoint as an API, it does happen])
- the collection of endpoints that comprise the bounded context as defined by the team
- the affordances made possible by their work, and the work itself
- the file or artifact that articulates the business intent provided by that interface (written to a specified standard like OpenAPI, AsyncAPI, etc.)
- the documentation of all of the above, and source code, mock data, CI/CD pipeline, and key registration shenanigans necessary to create a pleasurable Time-to-Hello-World (or TTHW) experience
What is the right terminology for all this stuff? Unfortunately, Wittgenstein can’t help us settle this debate. The way people use language is all over the place. The way they use ‘API’ (and related terms) is not the way we talk about hotdogs. There isn’t one, singular cultural understanding that we could point to and say “this is the one way”.
To aid comprehension, I’ve adopted the following language model. It doesn’t mean that this is the right way. As the famous George Box quote goes, “all models are wrong, but some are useful”. When somebody says they have a problem with their API, I ask questions to clarify which of the following things, in my mental model, they are referring to:
- API Specification - A technical standard, like OpenAPI 3.0, that defines how to describe an API’s interface in a general, broadly applicable way that is both a machine-parsable and human-readable.
- API Description - A file articulating a single API’s interface that fulfills the requirements and expectations of an API specification.
- API Interface - The obvious or described (and, according to Hyrum’s law, not so obvious) means to communicate with a set of functionality within a system.
- API Implementation/Code - The gobbledygook created by software developers necessary to accomplish a business function to be exposed via an interface.
- API Executable/Deployable - The version of code that is promoted to a live environment and responding to production requests.
- API Documentation - The collection of things necessary to convey sufficient meaning so that clients can successfully use the deployed API through the interface. This includes, but is not limited to, the API Description.
This is my model. It works for me but if you’re comfortable with a different set of terms, great! As long as those that interact with you regularly share the same model, communication is happening with the least amount of cognitive overhead as possible.
After reading that, I know what you’re thinking.
If this is your model, and people having different models is ok, why did you say ‘it drives me crazy that they refer to these documents as “specifications”’?
My problem, particularly with vendors, is when the language is imprecise. I chafe when words are used interchangeably, often without disregard. Sometimes it is even on purpose, a targeted erosion of discourse in order to make a sale. I hate when words become less about clear communication and more about memetic highjacking, attempting to associate, expand, and/or co-opt organic phenomena in the pursuit of shipping product. That’s how a useful term is rendered all but meaningless (see ‘AJAX’, circa 2005 to 2008, or what is happening to ‘microservices’ now).
Having a model, and using it consistently, implies there is a certain amount of thought and rigor put into coexisting with your fellow folks. Words mean things, dammit, and the time you invest in your words is time invested in helping communicate meaning to other people.
The other way, best case, is lazy. Worst case, its calculated obfuscation.
