Manually Define Collection for Existing API

When it comes to defining the API lifecycle for an existing API, sometimes you just need to roll up your sleeves and begin crafting a Postman collection from existing documentation that exists. Adding each individual request, parameters, and other details, while abstracting away authentication details using an environment and variables. Manually defining a collection for an existing API helps establish a cornerstone for an API that is already in production, but could use more investment in documentation, testing, and other areas of a modern API lifecycle. Preparing an API to possibly be iterated upon for a future version, or simply just make sure it is operating and being managed in a well defined away as part of overall API operations. This API blueprint enters the API lifecycle using the proven approach to defining a Postman collection, but then guides you through some of the most comment elements of an API lifecycle that are needed to get an API up to acceptable levels, in alignment with the rest of API operations.

Define

The Postman collection has become a proven solution for defining and troubleshooting existing APIs over the last five years. Providing a machine readable representation of the details of each API request and response that can then be used as an API client, to power documentation and testing. Postman collections provide an ideal foundation for defining what an API can do, then using that collection to power other stops along the API lifecycle, be shared internally via other workspaces, and externally via workspaces, URL, or an embeddable Run in Postman button. Providing an industrial strength approach to laying a foundation for a repeatable and well known API lifecycle for an existing API that is already in production.

Collection

Postman collections are a fundamental executable unit of value describing an API or collection of APIs intended to accomplish a specific business purposes. Collections resemble OpenAPI often times in how they are used, but diverge when it comes to being able to derive different documentation, mocks, tests, and complete or subsets of an API, providing a machine readable representation, but also one that can be executed as part of different lifecycle processes. Collections can contain many different API requests that can be organized by folders, possessing all the technical details of each API request, but also contains authorization, scripts, and other useful elements. Collections are the heartbeat of the Postman API platform, and begin with helping save requests defined while using Postman as an API client, but can also be applied to almost every stop along the API lifecycle when producing APIs, and speed up integration and automation for API consumers. Collections are extremely versatile, and represent a low-code vision of what is possible when it comes to working with APIs.

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

The most common form of API documentation is what can be described as reference documentation, providing a complete “menu” of all paths available for an API, along with all the parameters, headers, body, and examples to put to use. Ideally reference documentation is logically organized using folders and tags, and provides informative and useful summaries and descriptions for every individual path. Every API should have up to date and informative reference documentation that allows API consumers to understand the entire scope of an API, but also find exactly the path or paths they need to use as part of their application or integration. Reference documentation for all APIs is an essential part of a healthy API lifecycle, but teams should also be considering what other forms of documentation would help new users, specific domains, as well as describing some of the most common workflows an API is used for when it comes to desired business outcomes.

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 testing ensures that each individual API and collection paths comply with the contract that was put forth for each individual version of an API. OpenAPI for each API can be used to generate collections providing 100% coverage for all of the API paths present. JSON Schema provides the details of the contract, and when applied as part of an OpenAPI definition, you end up with a machine readable contract that can be manually or automatically tested against. It is common for collections to be defined for the contract tests of each API, and then have these contracts tests scheduled for regular run via a monitor, as well as included as part of CI/CD pipelines, providing robust coverage for contract tests that developers can manually execute, or automated as required as part of the API lifecycle.

Performance Testing

Performance testing establishes a benchmark for what can be expected when it comes to the response time for each API. The OpenAPI for each API can be used to generate collections that provide 100% coverage for all of the API paths present, or performance tests can be applied to just a subset of API paths. It makes sense to have performance test collections separate from other types of testing so that they can be run independently from contract, integration, or other types of tests. Helping establish that the performance levels are met from potentially different regions that reflect actual application usage of APIs. Providing a comprehensive look at the performance of an API from across multiple regions for 100%, or a sensible sampling of API paths, ensuring that APIs and the teams behind them are meeting their SLAs over time and across the entire API lifecycle.

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

Authentication begins on the producer side by selecting the appropriate authentication method when deploying an API to the gateway, setting the tone for how identity, authentication, and access control will work across the API lifecycle. Next, authentication can be defined as part of API consumption at the collection, folder, or individual request level, providing a configurable authentication layer for automating across API operations. Authentication should be balanced across both the producer and consumer side of the API lifecycle, putting well-known practices to work, allowing both sides to securely access, refresh, and engage with necessary authentication.

Security Testing

Security testing ensures that 100% of the surface area of an API is secure against the common types of attacks as defined by OWASP. The OpenAPI for each API can be used to generate collections that provide 100% test coverage for all API paths, ensuring that every API, and detail of the API is evaluated as part of common security practices. No API should move into production without having a security collection defined for testing for all of the known vulnerabilities, moving the security conversation further left in the API lifecycle–allowing developers to manually test as they develop an API, but then also allowing for the automation of API security testing as part of the deployment pipeline, or scheduled via a monitor. Security testing is just one part of a larger testing, but also security strategy, helping standardize how security is applied, while also properly equipping teams with the latest information and practices they need to be successful in securing API operations.

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 used to automate the scheduling of any contract test, taking any collection of API requests, complete with test scripts, combined with a targeted environment, and run in a variety of cloud regions on a recurring schedule. Providing the ability to independently execute the contract testing for each API, but then monitor the contract testing of each API over time to make sure nothing has changed. Providing the essential automation of contract testing needed to ensure it is consistently applied across all APIs, defining whether or not an API is not just meeting the uptime portion of its service level agreement, but actually is meeting business needs in an ongoing way.

Performance Testing Monitor

Monitors can be used to automate the scheduling of any performance test, taking a single, or a variety of API paths and making sure they meet the established baseline for response time. Monitors take your performance testing collections and allow for their execution on a recurring schedule, from any cloud region, with a specific set of environment variables applied at execution time. It is important that performance testing exist as their own collections so that performance testing monitors can become more precise in where and when they run, providing a robust look at API performance from the regions and times of day that matter the most. Performance testing monitors are essential in realizing a certain quality of service at scale across all APIs in production, providing an executable unit for understanding the performance of all API resources and capabilities over time.

Security Testing Monitor

Monitors can be used to automate the scheduling of any security test, taking collections that are generated from an OpenAPI and scanning every path for potential vulnerabilities. Collections provide the definition of the surface area of the API and test scripts provide the ability to automate security testing against each individual path, which is something that when combined with a specific environment, and then schedule to run as a monitor becomes a very robust way to scale security testing across the surface area all APIs.. Allowing any developer to add security testing to the stack of contract, performance, and other testing, but then also contributing to the overall security strategy applied across API operations, meeting the needs of individual APIs, but automating security in a way that prevents any API from falling behind, and becoming the next breach we’ll read about in the news.

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

Search is the fundamental element of API discovery, allowing API producers to search for existing APIs before they begin the development of new APIs, as well as API consumers to search for APIs they can use as part of their applications and integrations. A healthy API lifecycle depends on the ability to search internally and externally for APIs, as well as the operations around them. The indexing of workspaces, APIs, and the elements of the API lifecycle like documentation, mock servers, and tests should occur by default across all teams before the desired efficiency and velocity will be realized across operations. Postman platform search provides visibility across these dimensions of API operations, looking across private, partner, and public dimensions, but then also leverages a role based approach to what elements of API operations are surfaced based upon your role–making API search a priority as part of the API lifecycle.

Private Network

A private network is available for any team as part of the Postman platform. The private team network is accessible via the home page and provides a place to publish APIs, and each version of an API so they can be discovered by internal consumers. APIs can be added to the private network from the network itself, as well as part of managing the API within any workspace where the API is being managed. APIs in the private network will show up in the wider search, and allow for grouping and browsing by folder. Enabling teams who are producing APIs to easily increase the visibility of their APIs across teams, and beyond the workspaces where they are being developed. Increasing the chance that other teams will find before they begin developing a potentially duplicate API, or be able to put it to use within the application or integration they have planned.

Public Network

The Postman public network is where you will find APIs from leading providers like Stripe, Twilio, and Salesforce, while also being the place you can publish your own public APIs for discovery by millions of Postman users. The public network is where teams can discover other public APIs they can put to work, or help make their own public APIs more discoverable by other 3rd party consumers. APIs can be published to the public network by changing the visibility of the workspaces they are in to be public, making the APIs, collections, environments, and other elements viewable by anyone browsing or searching the Postman public API network. The public network isn’t just about API discovery, it is also about helping bring observability and engagement with public API consumers more discoverable and accessible. Moving from the many siloed API portals of the past, where API producers work to build their own API ecosystems, to where API producers just participate as part of a larger API platform ecosystem–where developers already exist.

Conclusion

This blueprint intends to provide a high level walk through of one possible way of defining a standardized API lifecycle beginning with the manual creation of a Postman collection that describes how an existing API should work. 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.