New API Using the OpenAPI Specification




Define

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.

Design

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.

Mock

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.

Document

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.

Deploy

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.

Manage

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.

Test

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.

Secure

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.

Monitor

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.

Discover

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.

The End