The Dimensions of the API Lifecycle
05 Aug 2021
Ok, I’ve gotten my recent immersion in thinking about the API lifecycle to a place where I think I want to put it to work on an actual API. I spent some on a draft OpenAPI extension to help guide my API lifecycle. Then I went through thirteen separate API lifecycle definitions that were shared with me in an earlier blog post and connected each stop along each API lifecycle to some element of the Postman API platform. This resulted in me further fleshing out my OpenAPI API lifecycle extension to a point that I feel it is wroth to use when guiding, demonstrating, managing, and governing one of my APIs. I don’t expect anyone to implement the full version of this, but I am hoping it is flexible enough that it can accommodate many different versions of the API lifecycle. This is why I tested it against those thirteen API lifecycle, because I wanted to see how it would hold up in theory to many different people’s versions. Here are some simple, basic, intermediate, and complete examples of what I am thinking this extension could be applied.
Simple API Lifecycle
Based upon what I’ve come across in issues in the OpenAPI spec repo, and what I’ve wanted when it comes to defining the API lifecycle, I wanted the API lifecycle extension to expand upon the versioning capabilities of the OpenAPI spec by allowing me to navigate between versions of the API, allowing me to walk backwards, forwards, and jump to the latest version. I also wanted it to provide me access to API environments, as well as the maturity and visibility of the API. I feel like these dimensions are pretty critical to exactly what the API lifecycle might mean on the ground within API Operations.
This OpenAPI API lifecycle extension adds a little bit of life and cycle each OpenAPI. It makes it so each versions aren’t orphans, and it let’s us know the state of maturity for an API, which is something that is heavily defined by the visibility of an API. These things lay the foundation for the API lifecycle. The number of stops, and the blast radius for changes to an API will vary significantly based upon these dimensions, and while the API lifecycle will still vary widely from API producer to API producer, it gets at some of the important dimensions of how people see the API lifecycle.
Basic API Lifecycle
To step things up a bit I wanted to add in some other essential elements that are often attributed to the API lifecycle, while keeping the simple dimensions I included above. This OpenAPI lifecycle extension gets at what I feel should exist at a minimum for any API I produce. They should have documentation, a basic set of tests, and I should be monitoring the tests to make sure that I am not breaking anything I expected the API do when I first published.
This provides a nice baseline for what folks could strive for as they are looking to move APIs from just being active to something you’d actually recommend folks use. Because the tests are defined as a Postman collection, something that can be paired with each environment, so you can automate the monitoring and testing of the API. Which for me, is something I’d like to see exist with each stop along the API lifecycle. Really, the API lifecycle should be API-driven. Which in my opinion opens up entirely new opportunities for automating the API lifecycle using the Postman platform.
Next, I’d like to step up the mocking, management, testing, monitoring, observability, and discovery of each API. I’d say that all of these, eluding maybe observability are stops you hear folks include as part of their definition of what the API lifecycle is. These are things that all contribute to the maturity of an API, and contribute to the potential velocity of an API, and how fast you might want to be versioning each API. The better defined your API lifecycle is, the more control you have over it, and this is what this OpenAPI API lifecycle extension all about defining and enabling.
I feel like this extension will have multiple uses and benefits, but I feel like it has the potential to help define, guide, and stabilize how people approach the API lifecycle. I’ve been studying the API lifecycle for over a decade and I still find myself struggling with being able to "see it". Without an ability to see the API lifecycle we are unable to effectively implement APIs across teams and operations in consistent ways. I am hoping this definition can help ground how I deliver across the API lifecycle, but also talk about and tell stories about the API lifecycle.
Robust API Lifecycle
Lastly, I wanted to just publish the most recent copy my OpenAPI API lifecycle extension. This is what I am going to use to move forward one of my demo APIs forward and further flesh out my definition of the API lifecycle. I am going to apply it to an existing API that I just want to move forward and iterate upon, as well as an entirely brand new API. I am looking to further flesh this extension, but ultimately get to a place where I can set the stage for applying governance in a more API lifecycle centered way.
The elements of my proposed OpenAPI API lifecycle extension are meant to be extensible, so that it can work for the different ways teams move through the API lifecycle. It is meant to expand and contract to work seamlessly across multiple platforms, allowing for use with any gateway, APM, or CI/CD solution. Wrapping common stops along the API lifecycle around API infrastructure across any cloud provider, or on-premise solution. This represents another level of flexibility I am looking for when it comes to defining the API lifecycle, accommodating everyone’s definition of what the API lifecycle, as well as how it functions underneath the hood.
What It Is Used For?
OK, so what is this extension going to be used for? Honestly I am not entirely sure at this time. Ultimately I envision this extension guiding any service or tooling that is used to move an API forward. I am looking for this extension to help visualize the API lifecycle and make it more real for people. To help me keep fleshing out this extension, I wanted to think about the different potential uses of this extension in context of reducing friction across the API lifecycle.
- Use to Guide - Help teams move APIs forward confidently.
- Use to Educate - Introduce teams to concepts along the way.
- Use to Demonstrate - Show how to implement stops along the lifecycle.
- Use to Manage - Provide ways to manage the full API lifecycle.
- Use to Automate - Allow for the automation of the API lifecycle.
- Use to Govern - Provide scaffolding for applying API governance.
I am looking to use this extension to articulate what the API lifecycle can be, what it is, and where each API fits into said API lifecycle. I don’t think that these API lifecycle definitions should be an OpenAPI extension. Ultimately I think they should be standalone files that are referenced as part of a central APIs.jsona>, or at the very least referenced from within an OpenAPI, and eventually AsyncAPI. I think each API lifecycle definition should reference and emulate a central API lifecycle strategy, and be used to standardize APIs across an organization. We will see how it goes. I have a lot more work to even prove that this thing will be useful at all, and allow me to coherently articulate what the API lifecycle is to folks, while convincing them that they can customize and bend it to their own definition of what the API lifecycle is. Lot’s to do, but regardless, I am learning tons. As usual.