Providing collections that are dedicated to onboarding new users with an API, helping reduce the cognitive load with understanding what is possible across an API, and presenting them with only the most common API paths they will need to get started with an API, reducing the time it takes from discovery to making their first API call as a new consumer.
The versatility and focus of collections are one of the things that make them so powerful. One type of collection that takes advantage of the ability for collections to become very precise is the observability collection. Providing another example of a Postman collection that can have a specific purpose, in this case, it is making sure consumers are onboarded as easily as possible. Providing a positive first impression, reducing the cognitive load present when someone first encounters an API, speeding up the time to first call, and optimizing the engagement by consumers. Transforming collections into another very precise way for benefitting API operations, contributing to all of it working well.
- Simplify -
- Focus -
null
The number of requests should be limited within onboarding collections, but the structure of them should maximize the structure of a collection by taking full advantage of the collection specification. Helping each granular capability to be as full-featured and robust as possible. The power of onboarding goes well beyond the limited scope and a more relevant title and description, pushing the producer to think about what other affordances can be provided to demonstrate what is possible with each set of digital resources, Helping maximize the functionality, but also reduce friction when it comes to getting started with an API, ensuring that new API consumers move from discovery and learning about an API to actually putting to work in some way in as short of time as possible.
- Folders - Logical separators within a collection for organizing and sequencing API requests for browsing by humans, but also automating with a runner or as part of a CI/CD pipeline, helping organize reference API collections, choreograph automation, and orchestrations across many different APIs as part of a single collection.
- Requests - An individual request being made to an API, possessing all of the technical details to make the request, including URL, authorization, headers, body, and even scripting to apply business logic before a request is being made to any API.
- 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. null
Common elements required to run an onboarding collection should be abstracted away to an environment. Allowing whoever has forked the capability collection to easily define what is needed to authenticate, operate, and maintain the state of the requests being executed. Abstract away secrets, tokens, and other keys/value pairs that are needed to execute the onboarding collection, but also potentially store data that may have been created, altered, and removed as part of running each individual resource. Enabling each onboarding collection to be powered, but also potentially for many different onboarding collections to be executed for a single specific environment.
- Variables - Key / value pairs of data that can be defined independently and stored within environments, but then applied across collections, providing variables that can be used for authentication, pagination, and other common aspects of working with APIs, allowing secrets to be abstracted away from each individual collection, but also other context that has little to do with the collection, or may define a state across multiple APIs and collections.
- Secrets - Add a layer on top of environmental variables specifically for managing secrets, making sure you have clear visibility and control of secrets and tokens being applied. null
Onboarding collections reduce what it takes to engage with each individual API resource, but also at the same time it widens the number of ways in which consumers can engage. The precision of an onboarding collection is perfect for very granular sharing via a URL, embedding within a blog post or on documentation using a button, but also allows resources to be forked, and have pull requests submitted, and potentially allow for merging of individual details of an API--reducing the cognitive load for defining, engaging, and executing each individual API resources, but also encouraging contributions from consumers via a single collection.
- Watches - Keeping track of the watches on workspaces, APIs, and collections to understand who is tuned into what is happening. Use watches as a metric for the number of consumers, contributors, and internal and external stakeholders who are tuned in.
- Forks - Making a linked copy of an API, or the mocks, documentation, tests, and other areas of the lifecycle defined as a collection to another workspace, allowing anyone to run on their own, make changes and enhancements, then if they desire, contribute back to the original and receive regular updates over time.
- Comments - Comments on APIs, collections and other elements of API operations allow for more tightly coupled and inline conversations to occur around entire elements or specific parts and pieces of elements, allowing teams to collaborate and communicate across the API lifecycle. null