Prepare your public collections for the Postman API Network

The Postman API Network is the world's largest repository of public APIs. API publishers and community users alike can leverage the power of the Postman API Network to make their Postman public workspaces, collections, APIs, and flows available for other developers to use.

To get started with the Postman API Network, you'll need to:

• Create and set up a public team profile.
• Create a public workspace.
• Import your first public collection.
• Curate your collection with relevant information.
• Set up Guided Auth for your collection.
• Share your collection with the world.

When naming your team, workspaces, and collections, note the following conventions:

• Profile/Team name: The name of an organization, such as Intergalactic Bank
• Workspace names: A service or solution name, such as Bank API Collections
• Collection: A use case, such as Savings Accounts

Ready to get started? Following is a step-by-step tutorial to help you craft a high-quality public workspace on the Postman API Network.

Set up your public profile

To host workspaces, you need a public team profile. The public team profile serves as the all-encompassing hub for any publicly listed assets on the Postman API Network. It's a place to introduce your organization and present all the public workspaces, collections, and flows you've made available.

When you create a Postman account, you're given the option to join any of the existing teams that share your company domain and have turned on team discovery. If you intend to share your public API assets on behalf of your organization, join your company's primary team. If a team doesn't exist yet, you can create it.

Create a new team

If this is the first time you're creating a team in Postman, you get to build your team profile and set your team up for success by implementing best practices from the outset.

Using this tutorial, you'll set up a public profile and implement best practices in the context of the Postman API Network. To learn more about team profiles on Postman, see Configure team settings.

To create a team profile:

1. Navigate to your account settings and select Create Free Team.

2. Name your team and enter a URL. As a discoverability best practice, name your team after your organization and change your URL to your organization's name.

   If your chosen URL is taken, contact Support. In the meantime, append -apis to the organization name. You can change the URL later.

Customize your new team profile

After you set up your team's name and URL, you'll be taken to your first team workspace. You'll revisit the workspace, but first you'll finish customizing your team profile.

Add your profile picture, banner, and favicon

You can manage your profile picture and banner directly from your profile page, but by following these instructions, you can also set your favicon.

1. Select your team profile picture from your home page and then select Team Settings.
2. Select the Team Profile tab and then select to upload your profile picture, banner, and favicon.

To ensure quality, use the following resolutions for your files:

• Profile picture: 2 MB max (official company logo or name)
• Banner: 720x96px <2 MB (official company colors, logo, or name)
• Image size: 16x16px or 32x32px (official company colors, logo, or name)

Other settings you can manage in this area include:

• Team name
• Team domain (URL)
• Public toggle (Team profiles are public by default)

Add your team summary and team description

Personalize your profile by filling out your team description, team summary, social media links, and highlights.

1. Navigate to your profile page while logged in. Either go to your Postman URL directly (go.postman.com/your-team-URL) or select your profile picture on the left side of your home page. Then select Team Settings > View Team Profile.

Edit each section available on your team profile while following the best practices described below.

Section	Best practice
Team description	Include a brief, high-level description of your company with as many mentions of your APIs as possible. This is a good place for high-level marketing keywords, like the word API. Add marketing graphics or YouTube videos, if possible.
Team summary	Include a short, one-line description of the brand. Use the word API at least once. Don't repeat any exact wording from the Team Description section.
Social media links	Postman enables you to add a website domain, a Twitter/X account, and a GitHub account. You can add as many links as applicable. The more social media accounts you link, the more confidence you convey.
Highlights	Pin all collections and workspaces. If there are too many collections and workspaces to list, select the most recent and relevant.

Create your first public workspace

After your public profile is branded and ready to showcase your work, create your first workspace. You'll be creating a public workspace to house your public-facing collections and other resources.

To create a public workspace, do the following:

1. Navigate to your home page and from the header select Workspaces > Create Workspace.

2. Select one of the templates or start with a blank workspace.

   If you choose to start with a template, the API demos and API testing templates are the best suited for public workspaces.

3. Name your workspace. Selecting the right workspace name is important for SEO, readability, and discoverability. Denote the services users can find inside. Examples of useful workspace names are:

   • [Your Org Name]'s API Collections
   • [Your Org Name]'s Public Workspace
   • [Your Org Name]'s [Service] Collections

4. Set the access level of your new workspace to public. Under Who can access your workspace?, select Anyone on the internet.

About workspace access levels

You can make your workspace public from the outset. However, this may not always be the best way to start. On the Overview page of your workspace in Postman under the Settings tab, you can change the access level of your workspaces at any time. For example, you can prepare a workspace for public consumption in private and then change it to public once you're satisfied with the resources you want to provide.

The Postman Secret Scanner scans your public workspaces to detect any exposed secrets, such as API keys.

• Create a public workspace from the start if you already have Postman collections you've tested and are confident they're ready for public consumption. This may be the case if you plan to fork existing collections into your new workspace or plan to import them from a repository. This option is best for seasoned users ready to get their project underway.
• Create a team workspace and publish later if you still need to curate your collections before showcasing them to the world. Start your workspace as a private team or personal workspace, curate your collections, make sure your source of truth is configured correctly, or ensure all secrets are removed from the environments, before you publish your workspace. Learn how to convert an existing workspace to a public workspace.

Whether personal, team, Partner (Professional and Enterprise plans only), Private, or public, workspaces enable you to work with and manage all your Postman assets.

Other workspace settings

The Settings tab also enables you to manage the sidebar and decide which elements to make available to your users.

For example, if you only want to share collections but don't need to make your API reference available, toggle the APIs off to hide the API reference tab from public users.

Workspaces dynamically evolve as you update your APIs, and the user experience improves as you curate the content you create for your users. Therefore, your workspace doesn't have to be perfect to be shared. Changes can be made later, and collections can be improved. Continuously manage your workspace to help provide the best possible user experience for your API consumers. Learn more about how to prepare your public workspaces for the Postman API Network.

Now that your workspace is ready to be populated, it's time to add your first collection.

Add your first collection

Postman Collections are fully customizable sets of API requests with corresponding documentation that you can curate and share with users to help them understand and start testing your APIs.

The best way to create your first public collection is to generate it from an existing API specification. You're able to import your API specification in several ways.

In this example, you'll generate your first collection by importing an OpenAPI specification residing on your local machine.

1. From the top of your workspace sidebar, select Import and then select the API specification you'd like to import or drag the file into the import section.

2. Select to import your specification as a collection only or as your full reference with a Postman Collection. Check the options in View Import Settings. Including your API reference can be useful, but in the interest of getting your first collection set up, select the first option.

   

3. Select Import. Your first collection appears in your workspace.

The automatically generated collection will use your API specification to generate basic documentation of your API automatically. You need to make sure the collection includes what a user needs to start testing your APIs. Leverage Postman to refine the collection and add more context and resources for your users.

Curate your collections

To help you in your curating process, consider these best practices compiled based on the most successful collections offered on the Postman API Network.

Double-check your API metadata

• Verify your requests - Sometimes, API specs are written in machine-readable formats that don't translate well to a human-readable collection. It's worth it to double-check your collection's metadata to ensure elements like the method, URL, and headers display correctly.
• Leverage folders - If your collection is large and has a lot of requests, consider grouping them into folders. Then, take it a step further and change the folder names to guide your users through steps or bundle the use cases. Grouping requests in folders can be an extra tool for improving your API's user experience.
• Add descriptions - Include rich information about all the different assets that can be found in your collections. You can add descriptions to folders, requests, parameters, and even full collections. Description fields can include rich resources like tables and screenshots. These fields use Markdown to give you a higher level of control over what you want to present to your users.

Add response examples

Adding response examples can be a big help to first-time users. Being able to preview what a response may look like can prepare users to know what to expect when testing your API and can even aid in troubleshooting if something goes wrong.

Add response examples everywhere you can. All you need to do is send a request, get a response, and save the response as an example.

Provide getting started workflows

Both the workspace overview page and the collection overview pages have full description fields that you can use to provide your users with direction. Most often, you'll recognize that the best collections on the API Network are those that include getting started instructions in their descriptions.

When writing your getting started instructions, keep the user experience in mind and include all the information a new user would need to achieve a successful call with your API.

• Point to the collections to fork first.
• Explain if the users need to open an account or build an app.
• Specify which environments are needed.
• Describe authorization requirements.

These description fields accept Markdown and enable you to include rich assets like images and embedded videos.

Use variables

Use variables throughout your collection. As you're reviewing your automatically generated collection and the metadata, include variables to enable value replacement when necessary:

• At the collection level for values that need to be linked to the collection itself.
• In the Environments tab, these variables can be decoupled from the collection and used with other collections.

Consider these best practices when creating and sharing environment variables:

• Specify example values as the Initial value for the variable. Don't add sensitive data as the Initial value because it's shared with users who can access the environment. The Current value is used in your local instance of Postman, and is never synced to your account or shared with your team unless you choose to persist it.

• To show users which environments work with your HTTP collection, you can pin environments to that collection. If your user forks the collection, pinned environments fork with the collection. To learn more, see Pin environments to collections. Users don't need to set up new environments from scratch as they can fork the environment alongside the collection, but they might still need to set up variables to use the API.

Protect sensitive information

Never include sensitive information such as API tokens in your variables. If you want to show the developer an example of the secret, use a placeholder for a variable or vault secret, but never a real secret. A placeholder for a vault secret is recommended because your API consumers can add the vault secret to their Postman Vault with their own value.

Implement quality-of-life best practices

After you set up your collection, you can enhance it by implementing some of the following quality-of-life best practices.

Connect to your source of truth

If your API specifications live in a repository on one of the major version control systems (GitHub, Bitbucket, GitLab, or Azure), you can import your specifications directly from your repository. This way, you can update your API reference and collections when new versions are created.

Leverage the Postman API to maintain your collections

Another way publishers are able to maintain their collections as new changes are made is by using the Postman API.

The Postman API enables Postman users to programmatically access data stored in their Postman account.

You can update your existing collections in a private or team workspace and then use the Postman API to update your public collections, without having to toggle them private.

Set up guided API authorization

Lastly, authentication issues tend to be one of the biggest blockers new users encounter when testing new APIs. You can simplify the auth process and ensure consumers' sensitive data is protected by leveraging Postman's Guided Auth feature. This feature prompts your users to provision access when using your APIs.

Guided Auth is the most secure option for your users because it enables them to securely save their credentials in Postman Vault. Once they set it up, they can reuse their credentials in future requests to your API.

Users who test against your configured URLs are prompted with your authorization instructions, even if they're testing your APIs on their own without the help of your collections.

You can set up multiple authentication schemes for your APIs for different endpoints on the same base URL.

Share your collections with the world

After you've branded your team profile, set up your workspace, curated your first collection, configured Guided Auth, and implemented quality-of-life improvements for your users, it's time to share your collection with the world.

At this point, if you haven't already, check that your workspace access level is set to public to ensure you're officially listed on the Postman API Network.

To guide your users from external sources, such as websites, blogs, developer portals, documentation, or your public workspaces, back to your Postman collections, you can embed Run in Postman buttons.

Learn more about best practices for sharing your public workspace with the world.

Next steps

You've created your team profile on the Postman API Network, built a high-quality public workspace, and provided some great collections for your users. This is only the beginning as public workspaces and the elements you include are dynamic resources that will grow and adapt as your APIs grow and change.

Using your public workspace metrics, you can see the types of issues your users are encountering, and then make changes to help your users overcome blockers.

Encourage users to use the commenting features across your workspace to create a feedback loop with them. You'll get a better insight into the issues they may be encountering and a chance to respond to them directly.

To stay in the loop, sign up for the Postman newsletter to be notified of new feature releases and relevant blog posts.