When Planning Your API Portal Do Not Hide APIs and Always Translate From IT To Something Humans Can Understand

While updating my APIs in higher education research this last week I came across an API portal I think tells an important story about an evolution in how we develop and maintain software. The current wave of web APIs that I cover has been working well because it has exposed a number of valuable resources, that once upon a time were only available in the realm of IT, making these resources accessible to a wider audience of developers, or even business users. 

This evolution has been slowly pulling back the curtain of IT, exposing more of it's inner workings, potentially simplifying, and decoupling valuable digital resources from legacy power structures. An important piece of this transformation is the translation of IT speak to language that the average human can understand, something that is playing out within API developer portals across companies, organizations, institutions, and government agencies. 

I touched on this subject with my work on the Environmental Protection Agency (EPA) Envirofacts API a couple weeks ago. With a little work I was able to expose a rich set of API resources, just by renaming the APIs, and hydrating some of the acronyms that were being used. While this is an example of the intersection of government IT power structures, it represents the same evolution.

As I was updating my university API work, I stumbled across the same evolution occurring at The Ohio State University. When you land on this API developer portal, you are given no signal that this contains course, and other valuable campus related APIs.

This API effort is born out of a classic IT lead project, and while it brings forward some healthy API patterns, it also carries forth the language and culture of IT. I am not saying the team behind the API portal is approaching their portal with intentional bias, these types of efforts are common, and often done by very well meaning groups, who only shortcomings are they don't think about reaching a widest audience possible. 

The idea that anyone should be able to land on an API portal, and be able to understand what is going on, is a foreign concept to many IT and developer groups. They build web service portals, system documentation, and other system doorways, thinking that other like-minded (IT and dev) folks will be coming there. They just aren't used to thinking that business leaders, researchers, data journalists, teachers, students, and any number of other folks might be coming there too.

Most groups that I come across like this, just need to be enlightened, and they will course correct. A smaller, but an often vocal group see no use in anyone outside the IT good ol boy club having access to resources--this is the old IT guard, and how power is protected. They will be gone soon, but for now you will have to just work around them. My goal is to just educate the API portal groups who are willing to listen, and stimulate API efforts from outside of IT lead groups when it is necessary, not to convert the critics.