Getting people to see APIs is hard. Even with the reality that each one of us individually makes thousands of API calls a day, and millions collectively as a business, almost nobody sees or really thinks to deeply about APIs. Even when business leadership is API aware and acknowledges their value and prioritizes investment in APIs, they won’t care about the details. I am fine with the upper levels of business leadership not wanting to dive into the API details, it is when this is the reality all the way down and up the enterprise ladder that I begin to get more concerned about things.
I have regularly mapped out existing enterprise API lifecycle and documented every step taken to produce an API, even bundled it with visuals, and distilled it down into an executive summary. There are always people who love to like and share these types of landscape maps on social media, but there is almost nobody who cares about the detail at the operation level—-even leadership in the company it was done for. The cognitive load is just too expensive for most people, even those whose job it is to know this stuff. You have to have three things to be able to care, 1) API knowledge, 2) domain knowledge, and 3) dedicated focus. Very few people are going to have all three, and it is likely they only have one of these areas.
I hear it a lot. “That is too much!”. “Why so many steps?”. “Where do we start?” All valid questions, except it isn’t my API landscape and lifecycle. It is yours. I am just mapping things out as they are. I will also need more context about where you are at in your API journey, and whether you are seeing things through the business or technical lens. This is one reason I am so interested in the public transit system as an analogy for API systems. When I am standing on a subway platform somewhere in the New York CITY MTA system I do not care about the entire system, I care about just a handful of data points that are well represented in this MTA kiosk.
If you study this MTA kiosk, what is it telling me? Where I am, what time it is, next train, previous couple of stops, next couple of stops, and what service updates impact my world right now or in the near future. I want this for not just producing APIs, but also for the governance of these APIs. The biggest mistake I consistently make is thinking that people want to see and have a discussion about the entire API landscape. When in reality, people aren’t equipped to have this conversation, and I am just going to overwhelm them. I am working on keeping my mouth shut more and not overloading folks, but this means I also have to get better at sharing a minimal amount of relevant information. But to do this, I need more context.
Reducing the information I provide to people sounds easy—-I just reduce the amount of information right? Well, if I am only going to share a small subset of information, it has to be the right information that is relevant to whoever I am speaking with. This is difficult. I need to know whether people are business or technical. I need to know generally how far along in their API journey they are. I need to know whether they are an API producer or consumer. There are so many dimensions where my conversation can go off the rails with someone, and when you are used to speaking about APIs within the echo chamber, it is something that proves to be very difficult to manage-—which is why most API pundits stay within the echo chamber.
I have my 25+ strategy areas, 175+ policies, and 400+ rules that represent where most enterprises should be focusing on when it comes to API governance. I am doing the hard work to translate the technical aspects of this into things business people will care about-—this is the role of the strategy areas and policies. Next I need to develop the MTA kiosk that will share where they are, the last 3 things they did, the next 3 things they need to do, and what the wider service updates are that may impact their world—and nothing more. This is easier said than done, but this post is about me doing this work. I don’t have a physical reference like MTA does with people standing on a platform within their transit system, so I need a way to geo locate people within the Matrix, I mean their API system.
There is a lot of missing context from the API discussions I see online today. I see a lot of obfuscation about where people are in their API journey because things are hidden behind the enterprise firewall and people can’t talk publicly about their journey. This makes it all very difficult for me to know which subway stop they are at and how to present them with relevant information. I will do my best to develop an API kiosk for people to use in their API journey, but I will have to build it out based upon my two platforms (APIs.io and API Evangelist), while also anonymizing what I learn from my customers. I have business and technical dashboards for my API governance approach coming to life, and my goal is to keep a little visual “kiosk” moving with you to help better inform you throughout your API journey.
