Lost In API Transit

I got on the New York Subway today heading for Penn Station to catch a train (New Jersey Transit) out to Princeton for a hackathon. As I was navigating my way through Metropolitan Transit Authority (MTA) and the New Jersey Transit I was thinking about my usage of API transit instead of API lifecycle. The number one response I had to this concept from readers was in regards the cognitive load experienced when you first look at a subway map that represents API infrastructure, and would anyone even know what I was talking about.

It’s true, when you first look at any of the API subway maps I’ve created so far, you scratch your head to figure out what they mean. I haven’t spent a lot of time making them coherent, but I am also just getting going with the work. Truthfully, they’ll get more complicated, over getting simpler. However, each time I first use the subway in NYC there is also a pretty significant cognitive load. I’ve ridden the subway many times, but each time I still have to study the map, learn the portion I need to get what I need done, and accept that much of it I won’t actually ever understand. I usually only learn what applies to me, and the more time I spend riding a transit system, the more time it comes into focus–something that applies to any transit system in the world I’ve used.

Think about when you start a new job, or adopt an existing legacy project as an API product manager. You do not immediately understand all the moving parts, absorb any diagrams, or documentation the first time you look at them. It takes time experiencing a system, before you will get acquainted, and become a local, like someone riding the MTA or NJT transit systems. Now that I live in NYC I’m going to spend time learning the transit system so I can get around, but I’m also going to invest energy learning it from an operators perspective, and understand the challenges they are facining maintaining, evolving, and keeping the system usable for users. I’m sure there will be a wealth of analogies in there for me when it comes to IT and API infrastructure.

Currently, I’m pretty lost on the MTA and NJT transit systems, but it’s slowly coming into focus. A significant piece of this is the maps that are available to me. Also the physical display systems available to me in the stations, as well as online, and on my mobile phone. I’m pushing forward the next generation of my API Subway MAP tooling at the same time. I’m creating a simple Siren-defined, Jekyll-driven, Github hosted map that helps me walk through a variety stops along the API lifecycle, along a handful of “lines” from design, to deployment, testing, and security. We’ll see how well I do bridging these concepts, but I’m hopeful that eventually it will come into focus, and I’ll stop being so lost, and develop a better understanding of what is going on.