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.

Author: Kin Lane

I am the chief evangelist for Postman, helping our community see the larger API landscape, and understand how Postman can help you be more successful across multiples stops of a modern API lifecycle.