I recently watched a BBC documentary about the history of the branding used as part of the London Underground. I’m pretty absorbed lately with using public transit as an analogy for complex API implementations, and moving beyond just using subway maps, I thought the branding strategy for the London Underground provided other important lessons for API providers. The BBC documentary went into great detail regarding how much work was put into standardizing the font, branding, and presentation of information for each London Underground, to help reduce confusion, and help riders get where they needed, and making the city operate more efficiently.
As I continue to study the world of API documentation, I think we have so much work ahead of us when it comes to standardizing how we present our API portals. Right now every API portal is different, even often times with multiple portals from the same company–see Amazon Web Services for example. I think we underestimate the damage this has to the overall API experience for consumers, and why we see API documentation like Swagger UI, Slate, and Read the Docs have such an impact. However this is just documentation, and we need this to occur as part of the wider API portal user experience. I’ve seen some standardized open source API portal solutions, and there are a handful of API portal services out there, but there really is no standard for how we deliver, brand, and operate the wider API experience.
I have my minimum viable API portal definition, and have been tracking on the common building blocks of API operations for eight years now, but there are no “plug and play” solutions that users can implement, following any single approach. I have the data, and I even have a simple Twitter Bootstrap version of my definition (something I’m upgrading ASAP), but in my experience people get very, very, very hung up on the visual aspects of this conversation, want different visual elements, and quickly get lost on the functional details. I’m working with my partners APIMATIC to help standardize their portal offering, but honestly it is something that needs to be wider than just me, and any single provider. It is something that needs to emerge as a common API portal standard. If we can bring this into focus, I think we will see API adoption significantly increase, reducing much of the confusion we all face getting up and running with any new API.