Blueprint: The Base of the API Lifecycle

This blueprint illustrates what we consider to be the base of the API lifecycle, providing a starting point for additional lifecycle variations elsewhere on this site. Depending on your priorities and your entry point, you may need to expand or remove from this base lifecycle to match your desired situation.

The API lifecycle will mean many different things depending on who you are talking to. This base API lifecycle isn’t meant to be a lifecycle definition that matches the needs of every enterprise organization, but is intended to provide you with a base example to help you begin thinking about what your own API lifecycle is. The blueprint is designed to provide you a base that you can add to or remove from, iterating upon until you find a common definition of the API lifecycle that works for your organization.


Define

Making 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.

  • 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.
  • 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.
  • Public Workspace - Some APIs will benefit from establishing a public workspace where 3rd party consumers can learn about an API, view the moving parts of it's operation, and engage with the team behind, making the API lifecycle much more transparent.
  • 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

Establishing a formal process and approach to designing an API helps establish consistency of each API that ends up in production, ensuring that APIs are developed using common industry and organizational patterns while establishing known practices for shaping the surface area and behaviors of APIs.

  • 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 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.
  • Comments - Comments on APIs, collections, and other elements of API operations allows for more tightly coupled and inline conversations to occur around entire elements or specific parts nd pieces of elements, allowing teams to collaborate and communicate across the API lifecycle.

Document

Having complete, accurate, and easy to follow documentation is essential for all APIs, alleviating the number one pain point for API consumers when it comes to onboarding with APIs, providing the human-readable technical details of what an API does, helping minimize the time to first API call.

  • 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.
  • 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.

Deploy

Providing a well-defined process to deploy an API into development, staging, and production environments, helping teams efficiently deliver future iterations of an API in a consistent and repeatable way, ensuring that APIs are properly tested, secured, and governed as a native part of the deployment process.

  • 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.
  • 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.

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.

  • 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

Ensuring that there is a consistent approach to identity and access management for each API, but also the proper security testing in place to make sure that all APIs are being secured in a consistent way no matter which team developed them, or whether they will be used for private, partner, or public use in applications.

  • 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

Making sure that all APIs are fully monitored by scheduling contract, performance, security, and other tests from multiple cloud regions, but also being able to monitor the activity, changelog, and state of an API using notifications, helping keep teams and consumers informed regarding the state of the APIs they depend on.

  • 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.
  • Activity - The changes made to any aspect of operations by team members, providing observability into when APIs, mock servers, documentation, testing, monitors, and other critical elements of API operations are changed, configured-- helping give a log of everything that happens at the operational level.
  • Change Log - A detailed history of the changes that have been made specifically to an API, showing all of the changes to the structure of an API as part of the design and development process, providing a single list of what has changed for consumers, and other stakeholders to get up to speed.
  • Notifications - Providing notifications about activity around the operation of any API, allowing for in-application, email, or type of message via integration with common platforms, providing real time updates about what is happening across API operations.

Discover

Enabling discovery across operations, helping teams find existing APIs before they develop new ones, properly matching API consumers with the right APIs, while supporting documentation, workflows, and the feedback loops that exist as part of the operation of internal, partner, and public APIs supporting applications and integrations.

  • 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.


Discussions

YAML

Printable

Slide Deck

Return to Main Page

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