The Dimensions of the API Lifecycle

Kin Lane
Written by

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.

# 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 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'
view raw openapi-lifecycle-extension-v0.2.0.-simple.yaml hosted with ❤ by GitHub

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.

# 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 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'
# Elements of the API Lifecycle
elements:
# Documentation
documentation:
label: Docs
guidance: http://example.com/guidance
elements:
# Reference Documentation
- type: reference
title: Reference Documentation
url: 'https://example.com/documentation'
collection: 'https://www.postman.com/collection'
# All Tests
tests:
label: Testing
guidance: http://example.com/guidance
elements:
- type: contract
title: Contract Testing
url: 'https://example.com/contract-testing'
collection: 'https://www.postman.com/collection'
# All Monitors
monitors:
label: Monitors
elements:
- type: contract
title: Contract Testing Monitor
url: 'https://example.com/monitor'
collection: 'https://www.postman.com/collection'
environment: 'https://www.postman.com/environment'
view raw openapi-lifecycle-extension-v0.2.0.-basic.yaml hosted with ❤ by GitHub

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.

Intermediate Lifecycle

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.

# 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'
# Elements of the API Lifecycle
elements:
# All Mocks
mocks:
label: Mocking
elements:
- type: sandbox
title: Mock Server
url: 'https://example.com/mock'
collection: 'https://www.postman.com/collection'
# Documentation
documentation:
label: Docs
guidance: http://example.com/guidance
elements:
# Reference Documentation
- type: reference
title: Reference Documentation
url: 'https://example.com/documentation'
collection: 'https://www.postman.com/collection'
# Management
management:
label: Manage
guidance: http://example.com/guidance
elements:
# Onboarding
- type: onboarding
title: Login / Registration
url: 'https://example.com/login'
# Plan
- type: aws-api-gateway-plan
title: Plan
url: 'https://console.aws.amazon.com/apigateway/home?#/usage-plans/859pid'
# All Tests
tests:
label: Testing
guidance: http://example.com/guidance
elements:
- 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 Monitors
monitors:
label: Monitors
elements:
- type: uptime
title: Uptime Monitor
url: 'https://example.com/monitor'
collection: 'https://www.postman.com/collection'
environment: 'https://www.postman.com/environment'
- type: security
title: Recurring Security Testing Monitor
url: 'https://example.com/monitor'
collection: 'https://www.postman.com/collection'
environment: 'https://www.postman.com/environment'
- type: contract
title: Contract Testing Monitor
url: 'https://example.com/monitor'
collection: 'https://www.postman.com/collection'
environment: 'https://www.postman.com/environment'
- type: performance
title: US East Regional Performance Testing Monitor
url: 'https://example.com/monitor'
collection: 'https://www.postman.com/collection'
environment: 'https://www.postman.com/environment'
- type: performance
title: US West Regional Performance Testing Monitor
url: 'https://example.com/monitor'
collection: 'https://www.postman.com/collection'
environment: 'https://www.postman.com/environment'
# Observability
observability:
label: Observability
elements:
- type: reports
title: Report Dashboard
url: 'https://example.com/reports'
- type: change-log
title: Change Log
url: 'https://example.com/change-log'
- type: activity
title: Activity
url: 'https://example.com/activity'
# Discovery
discovery:
label: Discovery
elements:
- type: network
title: Public Network
url: 'https://example.com/public-network'
- type: workspace
title: Public Workspace
url: 'https://example.com/public-workspace'
# Milestones for the API (Achieved and Target)
milestones:
# Design Review
- type: design-review
description: 'Went through design review.'
date: '2021-06-01'
# Staging
- type: staging
description: 'Left staging phase of development.'
date: '2021-07-01'
# Security Review
- type: security-review
description: 'Went through security review.'
date: '2021-06-01'
# Active
- type: active
description: 'Put into production as active API.'
date: '2021-07-15'
view raw openapi-lifecycle-extension-v0.2.0.-moderate.yaml hosted with ❤ by GitHub

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.

# 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'
# Elements of the API Lifecycle
elements:
# All Mocks
mocks:
label: Mocking
elements:
- type: sandbox
title: Mock Server
url: 'https://example.com/mock'
collection: 'https://www.postman.com/collection'
# Documentation
documentation:
label: Docs
guidance: http://example.com/guidance
elements:
# Reference Documentation
- type: reference
title: Reference Documentation
url: 'https://example.com/documentation'
collection: 'https://www.postman.com/collection'
# Onboarding Documentation
- type: onboarding
title: Onboarding Documentation
url: 'https://example.com/documentation'
collection: 'https://www.postman.com/collection'
# Workflow Documentation
- type: workflow
title: Business Workflow Documentation
url: 'https://example.com/documentation'
collection: 'https://www.postman.com/collection'
# Deployment
deployment:
label: Publishing
guidance: http://example.com/guidance
elements:
# GitHub Repository
- type: github
title: Github Repository
url: 'https://github.com/org/repo'
sync: true
# Pipeline
- type: github-action
title: Github Action
url: 'https://github.com/org/repo/actions'
# Gateway
- type: aws-api-gateway
title: AWS API Gateway
url: ' https://uab3sjk0mna.execute-api.us-east-1.amazonaws.com'
collection: 'https://www.postman.com/collection'
sync: true
# Management
management:
label: Manage
guidance: http://example.com/guidance
elements:
# Onboarding
- type: onboarding
title: Login / Registration
url: 'https://example.com/login'
# Plan
- type: aws-api-gateway-plan
title: Plan
url: 'https://console.aws.amazon.com/apigateway/home?#/usage-plans/859pid'
# SDKs
sdks:
label: SDKs
guidance: http://example.com/guidance
elements:
# Python
- type: python
title: Python Library
url: 'https://github.com/sdks/python'
# Node.js
- type: node.js
title: Node.js Library
url: 'https://github.com/sdks/nodejs'
# Go
- type: go
title: Go Library
url: 'https://github.com/sdks/go'
# All Tests
tests:
label: Testing
guidance: http://example.com/guidance
elements:
- 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 Monitors
monitors:
label: Monitors
elements:
- type: uptime
title: Uptime Monitor
url: 'https://example.com/monitor'
collection: 'https://www.postman.com/collection'
environment: 'https://www.postman.com/environment'
- type: security
title: Recurring Security Testing Monitor
url: 'https://example.com/monitor'
collection: 'https://www.postman.com/collection'
environment: 'https://www.postman.com/environment'
- type: contract
title: Contract Testing Monitor
url: 'https://example.com/monitor'
collection: 'https://www.postman.com/collection'
environment: 'https://www.postman.com/environment'
- type: performance
title: US East Regional Performance Testing Monitor
url: 'https://example.com/monitor'
collection: 'https://www.postman.com/collection'
environment: 'https://www.postman.com/environment'
- type: performance
title: US West Regional Performance Testing Monitor
url: 'https://example.com/monitor'
collection: 'https://www.postman.com/collection'
environment: 'https://www.postman.com/environment'
# Observability
observability:
label: Observability
elements:
- type: reports
title: Report Dashboard
url: 'https://example.com/reports'
- type: change-log
title: Change Log
url: 'https://example.com/change-log'
- type: activity
title: Activity
url: 'https://example.com/activity'
- type: apm
title: Datadog
url: 'https://datadog.com/dashboard'
sync: true
- type: aws-api-gateway
title: Gateway Usage Report
url: url: ' https://uab3sjk0mna.execute-api.us-east-1.amazonaws.com/usage'
sync: true
- type: uptime
title: Uptime Monitor Results
url: 'https://example.com/monitor/results'
- type: security
title: Recurring Security Testing Monitor Results
url: 'https://example.com/monitor/results'
- type: contract
title: Contract Testing Monitor Results
url: 'https://example.com/monitor/results'
- type: performance
title: US East Regional Performance Testing Monitor Results
url: 'https://example.com/monitor/results'
- type: performance
title: US West Regional Performance Testing Monitor Results
url: 'https://example.com/monitor/results'
# Discovery
discovery:
label: Discovery
elements:
- type: network
title: Private Network
url: 'https://example.com/private-network'
- type: network
title: Public Network
url: 'https://example.com/public-network'
- type: workspace
title: Private Workspace
url: 'https://example.com/private-workspace'
- type: workspace
title: Public Workspace
url: 'https://example.com/public-workspace'
# Governance
governance:
label: Governance
rules:
- type: design-rules
title: Design Rules
url: 'https://example.com/design-rules'
- type: management-rules
title: Management Rules
url: 'https://example.com/management-rules'
- type: documentation-rules
title: Documentation Rules
url: 'https://example.com/documentation-rules'
- type: testing-rules
title: Testing Rules
url: 'https://example.com/testing-rules'
# Milestones for the API (Achieved and Target)
milestones:
# Design
- type: design
description: 'Design agreed upon by stakeholders.'
date: '2021-05-01'
# Design Review
- type: design-review
description: 'Went through design review.'
date: '2021-06-01'
# Staging
- type: staging
description: 'Left staging phase of development.'
date: '2021-07-01'
# Security Review
- type: security-review
description: 'Went through security review.'
date: '2021-06-01'
# Active
- type: active
description: 'Put into production as active API.'
date: '2021-07-15'
# Retire
- type: retire
description: 'Planned retirement date.'
date: '2025-07-15'
# Deprecation
- type: deprecation
description: 'Planned deprecation date.'
date: '2025-12-15'
view raw openapi-lifecycle-extension-v0.2.0.yaml hosted with ❤ by GitHub

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.