Blueprint: The Base of the API Lifecycle

This blueprint illustrates a generic API lifecycle. It provides a starting point for subsequent lifecycle variations elsewhere on this site. Depending on your priorities and starting point, you may need to expand this base lifecycle to match your desired situation.

Every organization creating APIs has an API lifecycle, whether they know it or not. The difference separating high-performing API companies from those with inconsistent results is a thoughtful and practiced approach. Below are key aspects of the API lifecycle, common characterists worth focusing on, and how Postman’s API platform supports each.


Discover

Before starting a new API endeavor, it is crucial to discover if the solution to the problem you're trying to solve already exists. Building on already existing functionality brings products and services to market faster. Postman has several elements that make this discovery step easier.

  • 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.
  • Watch - Watching of some element of API operations, allowing team members, partners, or public users to signal they want to receive notifications of any change to an API and it's supporting elements, making API operations more observable and something that all stakeholders are able to stay in tune with as they evolve and change.
  • 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.

Design

Designing an interface is one of the most critical steps in the API's lifecycle. It involves making decisions on how the interface will look and feel when used. American software engineer Grady Booch calls these decisions "significant", where significance is measured by the cost of change. Once your API has its first user, the cost of changing that interface increases significantly. Applying the appropriate rigor at this stage of the lifecycle will decrease the likelihood that change is necessary later. This includes, but is not limited to, defining performance, functionality, and security expectations.

  • Techniques - There are numerous techniques that assist API producers in better defining their operations and the APIs and microservices they are delivering across these operations, such as Microservices Canvas, Jobs to be Done (JTBD), Event-Storming, Domain-Driven Design, and other well known elements of the API lifecycle.
  • Goals - Ensuring the goals behind an API are well defined and accessible as part of the operation of an API help ground a team's activity when it comes to supporting consumers and iterating upon API, helping ensure that the API design and operation is in alignment with business objectives.
  • 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.
  • Sharing - Sharing of elements used to produce or consume APIs across workspaces, externally with consumers, allowing an intended audience to view, download, and access artifacts and other elements of API operations so they and collaborate around the production or consumption of API resources and capabilities.
  • Documentation - Documentation published as human consumable HTML pages help potential API consumers learn about what an API does by describing the paths, channels, parameters, headers, schema, messages, and other building blocks of APIs, showing examples of what is possible or by providing an API client to make calls to each API as part of the documentation.

Publish

Publishing is the act of making an *implementation* available that executes a service's interface in an accessible environment. This act requires more than just pushing a deployment to a cloud host. Publishing an API entails communicating documentation and, in some cases, code to the appropriate audience.

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

Secure

An APIs usefulness to automation also makes APIs a potential target for malicious actors. Ensuring security is accounted for and applied consistently for all APIs produced is a significant step.

  • Role Based Access Control - Role based access control allows for the artifacts and elements for each API to have clear team access to only viewing and running or being able to actually edit and change, helping prevent unwanted changes to API elements across the lifecycle.
  • 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

To properly manage APIs and how they flow through the API lifecycle, it is vital to have accurate and up-to-date information. Postman provides several valuable elements to track APIs across the platform.

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

Manage

Markets, strategies, team experience, and professional expectations change. So too, do APIs. However, changing an interface is no trivial task, given the number of integrations depending on it. Learning to prioritize and schedule changes to minimize the negative impacts is a skill. Thankfully, Postman includes elements to navigate through this step of growing importance.

  • Versioning - Applying semantic versioning to individual artifacts to help manage change across each API and wider operations, providing a structured approach to how APIs are evolved, helping identify minor changes from patches, and clearly defining major revisions that would introduce breaking changes.
  • 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.


Discussions

YAML

Printable

Return to Main Page

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