API Transit - The Basics
02 Jan 2018
I have been evolving my approach to mapping out all the stops along my API research, using a subway map approach lately. It has been something I’ve been working on since 2014, and had developed as a keynote talk in 2015. My goal is to be able to lay out simple, as well as increasingly complex aspects of consistently operating an API. Something I’ve historically called the API life cycle, but will work to call API transit in the future.
Right now, I have two main approaches to delivering the API Transit maps. 1) API Life Cycle, and 2) API Documentation. The first is about applying consistent practices to API operations, and the second is about understanding API operations as they happen. In my mind, both these types of API Transit maps will eventually work in sync, but I have to work my way up to that. Right now, I’m focusing on the API Life Cycle version, which is becoming more about API governance, but I’m going to try and rebrand as API Transit. I’m using transit as a verb, “pass across or through” a standard, and consistent way of doing APIs. What some might consider API design, or governance, but I’m considering more holistically.
To support a couple of my consulting projects I am working on at the moment, I have published a simple API Transit project to help navigate some API teams through what I’d consider to be the basics they should be considering as they look to standardize how they deliver APIs across teams. It’s a basic single line, 19 stop API Transit map. It is something I will keep adding stops to, and expand many into their own lines, serving up much more detail, but for this first project I wanted to keep simple, and speaking to a specific enterprise audience. I don’t want to overwhelm them with information as they are just getting started on their API journey. They still have so much work to do in these 19 areas, I don’t them to get distracted with other areas, or feel like they are drowning in information.
My API Transit maps all run on Github, using Jekyll as the client. Each transit line, and stop is stored as Siren hypermedia stored in a Jekyll Collection. The resulting transit map, and details of each stop is just a simple HTML client which uses Liquid to render the data. This allows me to add stops, and lines as I need, expanding the API journey for each API Transit implementation. I still have routing challenges for the lines on the map. I have an editor for helping me plot where each line should go, but there are no easy answers when it comes to transit map layout, and is something that is proving to be more art than science, so I’m refraining from automating too much at the moment. I’m working on a routing algorithm, but just don’t have the time to perfect it at the moment.
Next, I’m working on more complex iterations of existing APIs, so more about documentation than governance, life cycle, or transit. I’m doing this with PSD2 as an exercise. Once I’ve done some more complex transit and specific API maps, I will work on combining the two, and applying the governance that exists in the transit map to a specific API, or set of APIs. Not sure where all of this is going, it is just a work in progress right now. It has been for almost three years, and I expect it will continue for many more years. If you are interested in having an API Transit map created for an existing API, or for a specific API governance process, feel free to reach out. I’m looking for more paid work to help push this work forward. Otherwise, it will just move along at whatever pace I can on my own steam!