--- published: true layout: post title: An OpenAPI Lifecycle Extension image: >- https://kinlane-productions2.s3.amazonaws.com/algorotoscope-master/uncle-sam-working-on-railroad-1.jpg tags: - Lifecycle - OpenAPI - Extensions --- Multiple API universes collided recently resulting in me spending some more time on defining what the API lifecycle is. A couple months back [](https://apievangelist.com/2021/03/11/what-is-your-api-lifecycle/)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](https://apievangelist.com/2020/08/02/managing-the-api-lifecycle-using-openapi-and-postman/), and created [a public workspace](https://www.postman.com/postman/workspace/postman-open-technologies-lifecycle/overview) 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](http://apisjson.org/), 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' |