Blueprint: New API Using the OpenAPI Specification

This provides a blueprint for beginning the API lifecycle by designing a new API using an OpenAPI, showing one possible lifecycle from end to end. Approaching the API lifecycle in a design-first way, while ensuring all the other essential areas of the API lifecycle are present.

This API lifecycle blueprint introduces the API lifecycle in what is widely considered to be an API design-first way, ensuring that each API is adequately defined by and leveraging the OpenAPI specification to design, mock, document, and iterate upon the design of each API before actually writing any code, or publishing an API to a gateway. This approach is widely considered to be desirable because it allows for API producers and even consumer stakeholders to be more closely involved in what an API will do as early on in the process as possible. This blueprint looks to provide you with a walk through of one of the more optimal and forward leaning approaches for establishing a standardized API lifecycle across your teams, helping ensure that the API lifecycle is driven by machine readable artifacts, and possesses clear steps for moving API artifacts from design to production in a way that everyone can understand while incentivizing collaboration at each stop along the way.


The most important first step of any API lifecycle is to make sure the operations around an API are properly defined, laying the foundation for being able to effectively design and bring an API to life, while also establishing a known place, or places to go to get all the information you need regarding each individual API, or groups of APIs. A little planning and organization at this early step of the API journey can go a long way towards ensuring the overall health and velocity of an API, and the applications and integrations that will depend on each internal, partner, or public API being delivered.

  • Team Workspace - Establishing and properly setting up a dedicated workspace for each API helps ensure there is always a single place to go to find everything that is happening with an API across it's entire lifecycle.
  • Team Members - Formerly defining who the team will be moving an API forward through all stages of it's lifecycle, providing a clear definition of who is responsible for each part of producing an API.
  • Github Repository - Having a dedicated Github repository for an API provides a single place where code and other artifacts can be managed, with a pipeline, issues, and other supporting elements an API will need to operate.


Having a formal process and approach to designing an API helps establish consistency and the precision of each API that ends up in production, ensuring that APIs are developed using common patterns across an industry, and within an organization, establishing known practices for shaping the surface area and behaviors of APIs that applications are depending upon. API design is something that just doesn’t impact the way an API is used, it is something that impacts almost every stop along the API lifecycle, and will reduce friction and increase velocity throughout the evolution of each API, and the applications and integrations that depend upon them.

  • OpenAPI - The OpenAPI specification provides a common vocabulary for describing the surface area of request and response APIs, as well as webhooks, ensuring that API producers and consumers are on the same page when it comes to integration, but also helps stabilize multiple areas of the API lifecycle providing a contract that can be used for delivering documentation, mocks, testing, and more.


Mocking how an API works and behaves provides an effective way for teams to collaborate, communicate, and iterate as part of the design of an API, but it also is something that can be used as part of testing, or just providing a sandbox environment for API consumers to learn before they actually begin working with any API in production. Effectively mocking an API takes a little time to set up and configure properly, but once available it will help reduce friction across the entire API lifecycle, helping teams more effectively communicate around an API throughout its journey.

  • Mock Server - A mock server helps replicate as much of the functionality and API would have in production, before the time to actually have to write any code, making APIs be more tangible and real early on in the lifecycle, allowing teams to rapidly design an API that meets the needs of everyone involved, providing usable elements that power design, documentation, testing, and other elements of the API lifecycle.
  • Examples - Examples of API request, responses, and messages used across API operations helps provide a versioned, evolvable, and reusable set of example and synthetic data that can make documentation richer and testing more relevant to actual business needs.


Having complete, accurate, and easy to follow documentation is essential for all APIs, and is something that alleviates the number one pain point for API consumers when it comes to onboarding with any API, expanding the number of API paths an application puts to work. Modern approaches to producing API documentation have moved beyond a single static version of documentation simply published to a portal, as well as there being potentially multiple forms of documentation for any single API. Helping API producers onboard consumers easier, reduce the cognitive load when understanding what an API does, and properly define specific business use cases of an API being put to work in an application or as part of an integration.

  • Reference Documentation - It is helpful for API consumers to have complete documentation for the entire surface area of an API, providing a complete reference of what is possible with an API to help consumers explore every path, parameter, schema, and other details of how an API works, making the resources and capabilities available within API something consumers can find and put to use without much work.


Establishing a well defined process to deploy an API helps teams bring new APIs to life, as well as assists them in more efficiently delivering each future iteration of an API in a consistent and repeatable way. Making sure APIs are deployed using known development, staging, production, and other agreed upon stages that actively apply other elements like documentation, testing, while natively contributing to observability. API deployment practices will likely have been well established as part of an organization’s traditional software development lifecycle, but is something that should be open to defining, standardizing, and making more repeatable and observable as part of the API lifecycle. The API deployment portion of the API lifecycle will be the most difficult for teams to properly define, articulate, and standardize across teams, but it will continue to be one of the most critical areas of the API lifecycle to do this for, otherwise it will be guaranteed to be a repeated source of friction across API operations.

  • CI/CD Pipeline - Like other aspects of the software development lifecycle, APIs benefit from well defined, repeatable CI/CD pipelines to deploy, test, automate, and orchestrate throughout the API lifecycle, publishing APIs to development, staging, production, and other stages, but then also ensuring other elements like publishing of documentation, and tests are baked into the process.
  • Gateway - API gateways provide a centralized or federated approach to the deployment and management of APIs at scale across an organization, leveraging commercial or open source API gateways to deploy APIs into development, staging, production, or other environment, allowing for the standardization of common elements of API management, and configuring APIs using common policies.


APIs should always be managed using a set of common, well-defined set of policies that define and govern how APIs are accessed via all stages of the API lifecycle, ensuring that every API has appropriate authentication, rate limits, logging, and other essential requirements of managing APIs at scale, helping strike a balance between making APIs accessible and the privacy and security concerns that exist. As API gateways and management solutions have been commoditized, many of the essential elements like documentation and testing have expanded into their own areas of the API lifecycle, leaving us with a core set of elements that can be applied by teams to help manage how APIs are put to work in applications and as part of system to system integrations.

  • Onboarding - Offering a consistent and well defined onboarding experience for all APIs, making it as easy and straightforward for consumers to onboard with an API, while also providing API producers with an easy way to onboard new consumers with their APIs without any custom work required, reducing friction when it comes to putting APIs to work by utilizing well known approaches to onboarding.
  • Usage Plan - Offering a standardized and well-defined set of usage plans for all APIs using commercial or open source API gateway or management solutions helps ensure that access to all APIs is done in a secure way that prevents exploitation by limiting the number of requests being made, or even billing for usage of an API based upon different dimensions defined within the usage plans applied.
  • Key - API keys provide the simplest form of access to an API, allowing consumers to sign up for an account, define what their application is, and then receive a key they can include in headers or other parameter to identify themselves, ensuring that API producers are fully aware of everyone who has access to an API, and all consumers have a way to clearly identify themselves and receive personalized usage data for each key.


A test-driven API lifecycle ensures that each API delivers the intended outcomes it was developed for in the first place, providing manual as well as automated ways to ensure an API hasn't changed unexpectedly and is as performant as required, helping establish a high quality of service consistently across all APIs. API testing should not be an afterthought and should be a default aspect of the API lifecycle for any API being put into production. API testing takes a solid investment in establishing proper testing practices across teams, but once you do the work to establish a baseline of testing, properly train teams on the process and tooling involved, the investment will pay off down the road.

  • Contract Testing - Contract tests can be derived from API artifacts like OpenAPI, JSON Schema, and GraphQL, and used to ensure there are no changes to what has been promised when an API was designed or developed, providing a repeatable test that can be run manually, on a schedule from multiple regions, or as part of a CI/CD pipeline to ensure contracts with consumers are upheld.
  • Performance Testing - Performance tests can be defined as individual tests using collections, pulling from one or many individual API paths and measuring the time it takes for the response to be sent, providing a test that can be run manually, scheduled across multiple geographic regions, or executed as part of a CI/CD pipeline, helping ensure an API is always meeting it's expected performance benchmarks.


Security must be its own area of the API lifecycle, but it is something that should span testing, authentication, and potentially other areas of the API lifecycle. Over the last five years the world of API security has expanded, while also moving further left in the API lifecycle as part of a devops shift in how APIs are delivered. There are a number of elements present when it comes to security, but depending on the overall maturity of API operations the available resources and prioritization available to adequately realize these elements vary.

  • Authentication - The consistent application of standard authentication as part of a standardized API management layer striking a balance between access to digital resources but ensuring that undesirable actors do not have access to valuable assets.
  • Security Testing - Security tests can be defined for any API using executable and shareable collections, testing for common OWASP vulnerabilities, as well as other more custom scenarios or business approaches, providing a single or suite of security tests that can be manually run, schedule across multiple regions, or executed as part of a CI/CD pipeline, automating security consistently across APIs.


Monitors can be used to execute any Postman collection applied to any environment. Due to the versatility of what a Postman collection can define, collections turn monitors into a powerful API automation and orchestration tool. Beginning with the ability to schedule contract, performance, and other types of tests, but then also allowing for automating specific workflows across many different APIs. Since collections can be used to define anything that can be defined via an API, monitors can be used to schedule the running of each capability from multiple cloud regions, applying many different environmental variables. Making monitors an essential, versatile, and executable part of defining how the API lifecycle works.

  • Contract Testing Monitor - Monitors can be setup for all API contract testing, scheduling the run of contract testing when needed and configuring to run from the regions that matter most to business operations, making sure that each individual API contract is never breaking with consumers, making sure that each API is delivering as expected on a 24/7 schedule.
  • Performance Testing Monitor - Monitors can be setup for all API performance testing, scheduling the run of performance testing when needed and configuring to run from the regions where performance makes the most difference on business, making sure that each individual API SLA is met, identifying API performance issues early on and responding to ensure there is no significant business impact.
  • Security Testing Monitor - Monitors can be setup for all API security testing, scheduling the run of security tests when needed, making sure that each individual API is regularly certified as being secured, ensuring that APIs do not become a liability due to changes, but also keeping all APIs compliant with the latest level of security testing that is occurring across an entire organization.


The ability to discover APIs at all stages of the API lifecycle is essential for reducing redundancy across operations, helping teams find existing APIs before they develop new ones, properly matching API consumers with the right APIs, while supporting documentation, relevant workflows, and the feedback loops that exist as part of the operation of APIs internally within the enterprise, or externally with 3rd party developers. API discovery does not live at the beginning or the end of the API lifecycle, but should be considered across all areas of the API lifecycle, ensuring that APIs, as well as the operations around them are as discoverable as possible, but well informed when it comes to privacy, security, and terms of service.

  • Search - Ensuring APIs are always available via search helps make sure that APIs can be found by consumers, but also by other producers who are looking to develop similar APIs, making search for APIs, as well as the operations around each API a critical aspect of the API lifecycle that should be considered as early on in the design and development of an API, but at least as it is deployed into production.
  • Private Network - Private API networks all organizations, groups, and teams to establish private catalogs of APIs, collections, and the other artifacts and elements around them, making it easier for producers and consumers to find APIs that are being designed, developed, or operating in production, making APIs more accessible but only to an intended audience.
  • Public Network - Public API networks allow for teams, APIs, collections, and other elements to be made available for searching and browsing by a public audience, helping API producers reach a larger audience, but also allowing consumers to quickly find the APIs and other resources they need in their applications and integrations, networking consumers with producers in an ongoing and collaborative way.

End of Life

Having a plan for the eventual retirement and ultimate deprecation of an API, or for specific paths or versions of an API should be a part of every API lifecycle, and even when there is no plan for deprecation there should be a process in place for setting consumer expectations for how long an API will be supported, as well as formal process to follow once retirement comes into view on the horizon. Planning for the end of life of each API will be commonplace, but only becomes a problem when there is no plan, or no communication with consumers.

  • Retire - The retirement of an API or specific version of an API is an inevitable thing and there should be a formal process in place to inform API producers about what the steps are in a process to retired, and set in motion the deprecation of an API, keeping an API or version of an API active for a specific amount of time, while acknowledging that at some point it will go away.
  • Deprecate - API deprecation occurs eventually for all APIs, and having a formal process to the deprecation of APIs or specific versions of an API helps API producers prepare for this inevitable future in a way that keeps consumers properly informed about what is happening, allowing the deprecation of APIs to happen consistently across all teams, groups, and the entire enterprise organization.

This blueprint intends to provide a high level walk through of one possible way of defining a standardized API lifecycle which is centered around an API design-first approach to delivering an API with OpenAPI at the center. This view of the API lifecycle will not work for all teams and for all APIs, but it does provide one possible overview that may work for many situations. Each element within this blueprint works to provide a simple overview of what is involved across the entire life of an API, with more detail present on the detail page for each element (if you are viewing this on the API lifecycle project site). If you are reading this via a PDF or printed version you can visit the landing page for this blueprint to access more information and view specific actions you might possibly consider taking as part of applying each element of this proposed lifecycle within your own operations. This blueprint is a living document and will continue to evolve and be added to over time based upon feedback from readers. If you have any questions, feedback, or feel like there is more information you need, feel free to jump on the Github discussion for this blueprint, or any of the individual elements present--the value this blueprint provides is actively defined by the feedback community members like you.




Slide Deck

Return to Main Page

This provides a link back to the home page if you need it.