Prepare an overview collection for your public workspace

You can create an overview collection as a starting point for your API consumers and encourage them to fork it to get started fast. Use an overview collection to summarize your APIs and get your API consumers to their first 200 OK response in the fewest steps possible. You can also showcase your APIs with common use cases and popular workflows.

If your public workspace contains many collections and primarily functions as an API reference, your workspace will benefit from an overview collection. Such a collection will help your users get started and help you market your public APIs on the Postman API Network.

Create a new collection

You can create an overview collection to orient your API consumers and get them started fast.

From the Postman sidebar, select Collections. Then, select Create new collection.

To learn more, see Create a new collection.

Name your collection

Open your collection's Overview tab, select the collection's name, and rename your new collection.

To learn more, see Configure a collection.

Name your collection something that communicates it's the starting point for the public APIs in your workspace. Use the following guidelines to choose a name:

• Use keywords that speak to your target audience. Choose words and phrases that your API consumers may search for, such as those that relate to what your API does, specific use cases, and common industry terms. For example, instead of "Data API", name your collection "Real-time financial data API".

• Choose a descriptive yet concise name. Convey what your API does in the fewest words possible. Use action-oriented language and avoid vague terms. For example, instead of "User API", name your collection "User account creation API".

• Be consistent across your workspace and collections. Consistency improves your API consumer's ability to scan and navigate your workspace and collections. For example, if you name your collections "Grocery Store API" and "Pharmacy API", name a similar collection "Retail Store API" (and not "APIs for Retail stores").

Tip: Use 🤩 emojis to make your collection name stand out.

Write a description

Open your collection's Overview tab, select the collection's description, and write a new description.

To learn more, see Configure a collection.

Use your collection description to get your API consumers to their first API request and 200 OK response in the fewest steps possible. Use the following guidelines to write a description:

• Introduce your APIs and the services they offer. Give your API consumers an overview of your APIs. You can add screenshots, videos, and links. List your APIs, highlight their value, explain what each does, and define any key concepts your API consumers need to understand. Help your users navigate your collection with a table of contents that links to folders and requests within your collection.

• Get your API consumers started. Focus on the steps each API consumer must complete to get their first 200 OK response, and document these steps for them. For example, if they must sign up for an account, give them a link to where they can sign up. If you host get started documentation elsewhere, link to it.

• Explain authentication and authorization. Often, authentication and authorization introduce the most friction between your API consumers and your APIs. Outline the steps someone must complete to make their first successful API call.

• Link to further documentation, such as tutorials. If you host your documentation elsewhere, link to it. For example, if you have integration guides and tutorials, link to them to let your users know what to do once they get their first 200 OK response.

• Link to help and the community. Add links to your support channels, forums, and community resources. This ensures your API consumers know where to go when something goes wrong.

Organize your collection with folders

You can organize your collection to be more intuitive and useful to your API consumers.

Next to your collection, select View more actions and then Add folder. To add subfolders, next to each folder, you can do the same by selecting View more actions > Add folder.

To learn more, see Add folders to a collection.

You can use folders and subfolders to help your API consumers navigate your collection and APIs. Use the following guidelines to organize your collection:

• Mirror your onboarding steps. Go back to your collection description and the steps you outlined there and mirror those steps with your folders and subfolders. For example, if you use multiple API requests to set up an account, put those in a folder called "Set up an account".

• Cover the basics, such as authentication and authorization. Ensure you cover the basics, such as authentication and authorization and any API request that gets your API consumers to their first 200 OK response.

• Showcase important use cases and workflows. Create folders to group your API requests by use case and workflow. For example, if you want to showcase your e-Commerce APIs, create "Add to cart" and "Check out" folders.

• Consider adding a support folder. Think about creating a folder that's dedicated to addressing common issues. Such a folder could include examples of typical errors and how to resolve them.

• Research what your users need. Before you finish preparing your collection, review your support channels, forums, and community resources. Identify your API consumers' most common challenges and address them directly in your collection.

Set up authentication and authorization

Postman recommends you set up Guided Auth with OAuth 2.0 for your domain. Once you set this up, and an API consumer goes to use an endpoint on your domain, the Postman app will prompt them to authenticate through Guided Auth. This is the fastest way to authenticate and creates the best developer experience for your API consumers.

If needed, Postman supports a variety of authorization types, which you can also set up for your users.

To learn more, see API authentication and authorization in Postman.

Set up Guided Auth for your domain

From the Postman header, select Team > Team Settings and then Guided Auth. Enter a name for the API, its base URL, and select OAuth 2.0. You must verify your domain and enter your API's authorization details.

You can also select one of the other authorization types.

To learn more, see Set up Guided Auth for public APIs in Postman.

Set up auth for your collection

If you're not ready to set up Guided Auth, you can set up authorization for your collection. All requests in the collection inherit the authorization details you set up.

Open your collection's Authorization tab and select an Auth Type. Enter as much of your API's authorization details as you can. Your API consumers will complete the remainder of the details.

To learn more, see Add API authorization details to requests in Postman.

Create variables and environments

You can create variables in your workspace to improve the developer experience for your API consumers. For example, you can create a variable for an API consumer's API key and use the variable throughout your requests. An API consumer can later update the variable's value with their API key in one place.

You can set up variables for different scopes, such as your collection or an environment.

Note: API consumers can't fork your global variables. Don't use them in your public workspace. Use collection and environment variables instead.

To learn more, see Reuse data with variables and environments in Postman.

Create collection variables

To create a collection variable, open your collection's Variables tab.

To learn more, see Store and reuse values using variables.

Create environments and environment variables

An environment is a set of variables specific to a context. For example, you can create two environments, one for your test environment and one for production. Then, you can create variables where you expect the value to be different for each environment, such as an API key. When your API consumer switches environments, the value switches for them.

To create an environment, from the Postman sidebar, select Environments. Then, select Create new environment.

To learn more, see Group sets of variables in Postman using environments.

Pin your environments to your collection

If you want your API consumers to fork your environments when they fork your collection, you can pin them. When you pin an environment to a collection, and someone later forks that collection, by default, that person will also fork the pinned environments.

Open your collection and, from the upper right of the Postman workbench, select the environment selector. Then, hover over the environment and select Pin to collection.

To learn more, see Pin environments to collections.

Write scripts and tests

You can use pre-request and post-response scripts to enhance your API consumer's developer experience. You can write scripts to automate tasks, transform data, add conditional logic, and give your API consumers immediate feedback, such as how to address errors.

For example, you can write a script that formats dates to the API's expected format, or validates whether a response's key-value pair is present. If your API uses access tokens, you can write a script that takes the token from a response and uses it in later requests.

To learn more, see Test APIs and write scripts in Postman.

Write pre-request and post-response scripts

Open a response, folder, or collection and select the Scripts tab. Then, select Pre-request or Post-response and write your script.

To learn more, see Use scripts to add logic and tests to Postman requests.

Use the Package Library to reuse scripts

Open a response, folder, or collection and select the Scripts tab. From the right of the Postman workbench, select Open package library. Then, select New Package.

To learn more, see Reuse scripts in Postman.

Pin your collection to your workspace overview

You can make your collection quicker to access by pinning it to your workspace's overview.

Open your workspace's Overview tab, select Pin collections, and pin your collection.

To learn more, see Pin collections to workspaces.

Evaluate the developer experience

Before you share and promote your new overview collection, walk yourself through the steps you outlined in the collection. Invite others on your team to do the same.

Gather feedback and iterate to improve the developer experience. Continue to iterate until you're satisfied you can get your new users to their first 200 OK response in the fewest steps possible. Always put your API consumer's experience first.