Multiple API universes collided recently resulting in me spending some more time on defining what the API lifecycle is. A couple months back I asked a bunch of folks in my Twitter timeline what their API lifecycle was, then I sat down to take another look at how I manage the API lifecycle using Postman, and created a public workspace to help me evolve my thoughts on this subject. As part of this work I went through any OpenAPI, AsyncAPI, or JSON Schema issues looking for anything that might speak to what folks are looking for when it comes to the API lifecycle. I have done a lot of thinking about the API lifecycle over the years, and you can see this work across API Evangelist, and as part my work on APIs.json / APIs.yaml, but to help satisfy requests I am getting from within Postman, from our customers, and as part of my work within the OpenAPI, AsyncAPI, and JSON Schema communities, I wanted to spend some time thinking about the API lifecycle—-this time grounded in a potential extension for the OpenAPI specification.
Proposed Extension for OAS
There is no better way to gather feedback from folks than just putting something out there and letting folks on the open web step up and tell me what is wrong with it. It is the beauty of how the open web, social media, and API space work. ;-) To release the hounds, here is a quick draft of an OpenAPI extension that for me speaks to the different dimensions of how I see the API lifecycle, providing one possible machine readable look at how we can communicate and automate around our APIs as they evolve, mature, and go away.
| # An extension for OpenAPI | |
| x-lifecycle: | |
| # Navigating Change | |
| version: | |
| current: 'http://example.com/next' | |
| next: 'http://example.com/next' | |
| previous: 'http://example.com/next' | |
| # Development | |
| # Staging | |
| # Production | |
| environments: | |
| # Environment for development | |
| - name: Development | |
| url: 'https://www.postman.com/environment' | |
| variables: | |
| base_url: 'http://example.com/development' | |
| api_key: 'xe3847d3J78393jkdm1123' | |
| # Environment for production | |
| - name: Production | |
| url: 'https://www.postman.com/environment' | |
| variables: | |
| base_url: 'http://example.com/production' | |
| api_key: 'xe3847d3J78393jkdm1123' | |
| # Design | |
| # Pre-Release | |
| # Active | |
| # Recommended | |
| # Retired | |
| # Deprecated | |
| maturity: 'Active' | |
| # Public | |
| # Internal | |
| # Group | |
| # Partner | |
| visibility: 'Public' | |
| # Essential Building Blocks of the API Lifecycle | |
| buildingBlocks: | |
| # All Documentation | |
| documentation: | |
| # Reference Documentation | |
| - type: reference | |
| title: Reference Documentation | |
| url: 'https://example.com/documentation' | |
| collection: 'https://www.postman.com/collection' | |
| # Workflow Documentation | |
| - type: workflow | |
| title: Workflow Documentation | |
| url: 'https://example.com/documentation' | |
| collection: 'https://www.postman.com/collection' | |
| # All Tests | |
| tests: | |
| - type: contract | |
| title: Contract Testing | |
| url: 'https://example.com/contract-testing' | |
| collection: 'https://www.postman.com/collection' | |
| - type: performance | |
| title: Performance Testing | |
| url: 'https://example.com/performance-testing' | |
| collection: 'https://www.postman.com/collection' | |
| - type: security | |
| title: OWASP Top 10 | |
| url: 'https://example.com/owasp-security-testing' | |
| collection: 'https://www.postman.com/collection' | |
| # All Mocks | |
| mocks: | |
| - type: sandbox | |
| title: Mock Server | |
| url: 'https://example.com/mock' | |
| collection: 'https://www.postman.com/collection' | |
| # All Monitors | |
| monitors: | |
| - type: uptime | |
| title: Uptime Monitor | |
| url: 'https://example.com/monitor' | |
| collection: 'https://www.postman.com/collection' | |
| environment: 'https://www.postman.com/environment' | |
| - type: performance | |
| title: Regional Performance Monitor | |
| url: 'https://example.com/monitor' | |
| collection: 'https://www.postman.com/collection' | |
| environment: 'https://www.postman.com/environment' | |
| # All Reports | |
| reports: | |
| - type: overview | |
| title: Dashboard | |
| url: 'https://example.com/monitor' | |
| collection: 'https://www.postman.com/collection' | |
| # Milestones for the API | |
| milestones: | |
| # Design | |
| - type: design | |
| description: 'Design agreed upon by stakeholders.' | |
| date: '2021-05-01' | |
| # Review | |
| - type: review | |
| description: 'Wentn through architectural review.' | |
| date: '2021-06-01' | |
| # Staging | |
| - type: staging | |
| description: 'Left staging phase of development.' | |
| date: '2021-07-01' | |
| # Active | |
| - type: active | |
| description: 'Put into production as active API.' | |
| date: '2021-07-15' |
You can find this extension in the public workspace I am using to define the API lifecycle. Feel free to highlight any part and leave inline comments within the workspace letting me know what you think about each property. Historically I do not believe that any of this should live within OAS, and I feel it should live within the APIs.json / APIs.yaml index for an API, but I know folks have a lot of apprehension about yet another specification, and there is a lot of attention place on the OpenAPI specification today. This is an exercise I will continue for event and message driven APIs using AsyncAPI, as well as pure schema using JSON Schema, but for this round it is all about doing for OpenAPI. Like most of my writing here on API Evangelist I am just looking to get something out there and gather feedback from other smart folks in the space, and once I wrap my head around the meaningful dimensions of the lifecycle for request and response APIs, I’ll focus some time on other specifications.
Dimensions of the API Lifecycle
If you look at my earlier post where I ask folks what their API lifecycle is, you’ll see that ultimately there are many different dimensions to this conversation. Some are about the artifacts and versioning, others are more about the environments, where others are about the tangible building blocks that emerge across the API lifecycle. Ultimately I want to create an extension that is flexible enough to fit 90% of the ways folks see the API lifecycle, but it is such a sprawling world I have to start somewhere. In this first draft I am looking to build around a handful of dimensions using these properties:
- Version - This is about navigating between versions, and I am relying on the core OpenAPI version property to define the existing version.
- Environments - Each of the environments available for an API provide a lot of context that influence how people see the API lifecycle.
- Maturity - The overall maturity of an API is a verify significant factor in how people view what the API lifecycle should even be for an API.
- Visibility - The visibility of an API will very much influence the extent of the lifecycle for an API, as well as the scope of the audience.
- Building Blocks - I struggled with the name for this dimension, but ultimately landed on what I consider to be the essential building blocks.
- Milestones - I feel that the lifecycle is very much defined by a handful of meaningful milestones that define how far along an API is.
This extension is way too verbose for my liking, but it gets at the critical dimensions of what I feel API lifecycle means to everyone. Next I will workshop this draft extension against all of the API lifecycle definitions folks provided to me and find ways of bending it to meet all of those expectations. Then I will take an existing demo or template API that I have an iterate upon it for a couple of versions, and see how my extension holds up in use across multiple OpenAPI definitions. Then I’ll see what other comments and feedback comes in via the workspace I setup, via Slack, and on the Twitterz. After that I will consider distilling down into maybe a suite of extensions, and think about what a minimum viable usage of it will be. Ultimately I know I want make everyone happy, but that isn’t my goal. I want to get something I can use to guide conversations, and use as guardrails to move this conversation forward even just a little bit. Success would be getting something in place for OpenAPI, AsyncAPI, and JSON Schema, and then get a handful of API service and tooling providers to put to work in some way.
I have spent way too much time over the last decade thinking about the API lifecycle, and I have seen way too little movement in providing meaningful vendor independent guidance for folks trying to get a handle on their API operations. It is one of those sprawling and highly opinionated conversations that seem to go nowhere, and can easily be shut down with some run of the mill criticism. Like with most of my work I’ll keep putting something out there and weather the criticism until I get something that speaks a meaningful cross section of the space. I want to get the feedback of the usual API echo chamber, but then I want to push to get out of the echo chamber and see what is needed for the average API product or engineering manager on the ground within the enterprise. APIs aren’t just a trend anymore, and are something that every company, organization, institution, and government agency is struggling with. We need some sort of guard rails to provide folks to help them move forward, evolve, and iterate in a standardize way. I am hoping this thinking can help continue to influence things, get the attention of the folks leading each of the API specifications, as well as API service and tooling providers, and begin laying a better foundation for the API lifecycle.
