Learning to Use Our Words Better When Defining Our APIs

I am playing around with the Open API for the Oxford Dictionaries API, and I'm struck by the importance of not just dictionaries like the Oxford Dictionaries but also the importance of OpenAPI and of API providers defining their APIs like the Oxford folks have.

While we aren't as far down the road as we are with the English dictionary, we are beginning to make progress when it comes to defining the paths, parameters, and other characteristics using OpenAPI, learning to speak and communicate in the digital world using APIs.

We use words to craft titles, paragraphs, outlines, and other ways that we communicate in our personal and professional lives. We also use words to craft titles, paragraphs, outlines, collections, and other ways our systems are communicating in our personal and professional lives using the OpenAPI specification.

In both these forms of communicating, we are always trying to find just the right words or series and orders of words to get across exactly the meaning we are looking for — we just have centuries of doing this when it comes writing and speaking, and only a decade or so of doing this with defining our digital resources using APIs.

Eventually, I'd like to see entire dictionaries of JSON Schema, ALPS, or other machine-readable specifications available by industry and topic. The way that we craft our API definitions and design our APIs often feels like we have barely learned to speak — let alone read or write. I'd like to see more reuse of common dictionaries already in use by leading API providers, and I'd like to see us get more thoughtful in how we express ourselves via our API definitions.

The most successful APIs I find out there don't just provide a machine-readable interface — they provide an intuitive interface that makes sense to humans while also being machine-readable for use in other systems.

It feels like to me that we should be integrating the Oxford Dictionaries API into our API design tooling, letting us suggest, autocomplete, and discover better ways to articulate the meaning behind our APIs. API design editors could use the Oxford Dictionaries API to help developers attach more precise meaning to the names of paths, parameters, and other aspects of defining our APIs, much like word processors have done for the last couple of decades.

Most APIs that I come across do not have any sort of coherent name, ordering, or structure, and the few that have deployed an OpenAPI or another machine-readable format often feel like cave writing and lack any coherent structure, purpose, or meaning. We have a long, long way to go before our systems learn to communicate even at a first-grade level.