Prepare your public workspace for the Postman API Network

Before making your APIs available on the Postman API Network, Postman recommends following these best practices and tips to help API consumers begin using your APIs.

Update your team profile

Update your team profile with important information about your team. Add information that identifies you as the real company on the Postman API Network. By default, your profile is only visible to your Postman team. Make your team profile public to make your profile show up on the Postman Explore page.

Organize your public workspace

You can organize the requests in your public workspace using collections and folders to help consumers begin interacting with your APIs. Collections enable you to group saved requests, and folders enable you to organize requests into folders by category, such as domain, service, and use case.

A workspace is a group of schemas, collections, variables, tests, and more that describe how to interact with your APIs. Typically, developers begin with collections when learning how to interact with APIs. Keeping your requests organized in collections and folders will help guide consumers towards requests relevant to their interests.

Create API examples for different use cases

You can create collections with specific example use cases to help consumers fork your collections and begin interacting with your APIs. Example use cases can include authentication and authorization, automation, and integrations.

Create environments for different use cases

You can create environments for different use cases, such as testing and production, and add them to your public workspace. This helps consumers understand what they need to configure with your API for their use case.

Protect sensitive data

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.

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

Write detailed documentation

Write detailed documentation for each collection and request to help consumers learn how to consume your APIs. The following best practices will help you write clear and concise documentation:

• Standardize the language in your workspace and its APIs.

• Use meaningful names for requests, collections, and folders. Use names that developers would expect.

• Reuse variables throughout your collection. Use variable names that are meaningful and set a clear expectation for their related values.

To learn more about writing detailed documentation, see The Good Documentation Checklist.

Define and describe variables

For your variables, you can write documentation describing the expected value and provide example values. Variables can be defined independently or stored within environments, and then applied across collections, enabling you to use variables for authentication, pagination, and other aspects of working with APIs. Variables can also define a state across multiple APIs and collections.

Write descriptions for folders and requests

At either the collection or folder level, Postman recommends writing detailed descriptions that explain how to sign up for and get started with your API. You can use keywords in your descriptions to increase your API's discovery in organic search results and Postman search results.

To learn more about collections and folders, see Create and manage request collections in Postman.

Add examples to requests

Save examples of your API's requests, responses, and messages to use examples in your documentation. This enables consumers to test your API using example data.

Add authorization details

You can create documentation explaining how to authorize with your API. You can mention this in the workspace description or documentation description if you have several API request workflows or a more complicated authorization schema. To learn more, see Including authorization details.

You can also set up Guided Auth for your API. This enables Postman to automatically recognize a request to your API that requires authentication, and prompt your API's consumers with steps to set it up.