{"API Evangelist"}

Establishing Common Dictionaries That Industries Can Use In Their API Design

I’m going through each of the 100+ business sectors I track on as part of my API Stack. As I make my way through each sector, and generate Swagger, and APIs.json files, the language of the resources used across a particular sector starts to come into focus. I’m talking about the words used for crafting URLs, parameters, and the underlying data models for common APIs.

In a perfect world everyone would come together and use something like Schema.org, and work to extend, in an organized, collaborative way across different industries—I would call this the Oxford English Dictionary (OED) approach. Unfortunately what we have is a shitload of dialects popping up, driven from the dark depths of our legacy IT infrastructure, only seeing the light of day when an API gets exposed, and the dialect used by an isolated IT tribe all of a sudden becomes part of the mainstream world.

Some weeks my inbox seems to reflect where my research is going, and as I ponder the language used by popular news sites like NYTimes, USA Today, and NewsCred, I get an email from a reader in Europe, who works at the equivalent of BBC their country, who asks:

Currently I'm thinking about the API vocabulary and i wonder if there is some kind of standard out there when it comes to the verbs, parameters, etc. that are used for Media/Broadcaster API`s. I think there should be some kind of standard (used by netflix, bbc, espn, abc, etc..) Do you have any idea if there is such a standard?

If there is a schema.org for the broadcasting industry I’m unaware of it. As I generate a crude dictionary for each of my API Stack business sectors I will stop, and conduct some due diligence on what is already out there for each industry regarding standards, etc. I’m assuming if there is, it won't always be Internet ready, let alone API ready, but hopefully there is already something that is driven by the industry that can provide a starting point.

I’ve talked about the need for a common dictionary, when it comes to API design, in my thoughts on a perfect API design editor. I will work to publish any dictionaries that I aggregate, as they come into focus. As with much of the API space I suspect that dictionaries will be defined from bottom up, using common slang used in the space, as opposed to a top down from coordinated OED approach, but hopefully by aggregating and educating API designers we can make strides towards a more coherent API space in some of the business sectors currently being impacted by APIs.