Intermediate API Skills: Workflow Collections
There are many different ways to put Postman Collections to work for your API operations. The most common usage is what we call a reference collection, which is about defining all of the details of your RESTful or GraphQL API. However, some API providers are beginning to use Postman collections in new and interesting ways, offering up more of what we consider Workflow style collections. These still provide details of API requests, but do so in a way that represents a specific business task, objective, or workflow. Workflow collections provide a single machine-readable definition of what an API does, but organized in a way that centers around helping a developer or non-technical user understand how to accomplish a precise API-driven workflow.
Workflow collections focus on the business task at hand, abstracting away the technical details of an API call, as well as potentially connecting, organizing, and making APIs more actionable. There are several fundamental building blocks that help API providers develop workflow collections, with some pretty versatile concepts that can define more meaningful actions to take against an API. They are organized in a way that makes more business sense.
- Folders – Collections let you organize API requests into folders, nesting and organizing, and helping reduce the cognitive load when it comes to getting up and running with an API.
- Authorization – The ability to authenticate with APIs using any of the common patterns, including API keys, OAuth, Basic Auth, and AWS Auth keeps API access from collections secure.
- Environments – Defining variables as part of a wider environment definition lets you apply them to workflow collections, populating specific values that contribute to a business outcome.
- Steps – You can think of API requests as steps in an overall workflow, moving beyond what each individual request can do, and focusing on what is possible when they are chained together to achieve a specific business objective.
- Pre-Request Scripts – Collections allow you to craft JavaScript functions that run before each step is executed, performing validation, conversions, and other processes that help automate and enrich the workflow at each step along the way.
- Post-Request Scripts – Crafting JavaScript functions that run after each step is executed, extracting values, running tests, performing logic, and automating other aspects of the workflow makes it perform the outcomes desired.
- Comments – The ability to add comments to each individual request allows collection managers and users to annotate each request, opening up a conversation with all stakeholders.
- Runners – Running a collection automates the execution of a workflow as part of a schedule, embedding it as part of a CI/CD pipeline, or allowing the runner to be triggered as part of any other event.
Workflow collections go well beyond API reference collections. They take advantage of the power of Postman to realize real-world tasks that need to occur via APIs. This allows you to use the same patterns across desktop, web, mobile, and device applications, by defining them as machine readable, portable, shareable, executable units of API value. Developers and business users can set business processes into motion, simply by stitching together multiple API requests into a single coherent workflow that reflects desired business goals.
We have begun to see more experienced Postman users move beyond just providing reference definitions for their API consumers, working harder to be more creative in how they craft workflow collections, making their APIs more accessible to developers and business users. This is resulting in workflow API collections intended for analysts, sales teams, and other business divisions, tailoring Postman collections to accomplish many different common tasks these users encounter.
Thanks for the overview article, it is interesting the approach and one thing I am usually doing is to copy-paste raw API requests into workflow folder, for Ex. imagine I have a cart folder with creating, update, delete and read API requests; now when I want to build the workflow to add an article to cart I can copy-paste the read and update API into the workflow folder.
Now the question is: how can I avoid duplication, is there a smart way to reference the original API from the workflow folder in order to have everything consistent when the API evolves?
thanks for the time
Hello. You can version individual collections currently, but there is no mechanism for managing the provenance and evolution of collections, especially the derived workflow collections from the original reference collections. We are working hard to understand the different ways in which our consumers use Postman collections–this work will inform how we shape the road map to provide more management solutions for handling the API life cycle for individual APIs, and the derivative workflow collections. I am currently playing with some proofs of concept via the Postman API for managing–stay tuned for more details.