API Network guidelines

Adding your team profile and collection docs to the API Network can expose your services to more potential users and provide them with the tools to onboard and adopt your API. To get the best out of your API Network listing, follow a few tips that will aid discovery of your documentation, making it and your collection templates as usable as possible.

API Network Homepage

Check your collection in the app

Your documentation represents a Postman collection, with both the textual information content—and the executable requests bundled via the Run in Postman button—pulled from your collection setup in Postman. For this reason, it's worth walking through the process of importing the collection yourself, checking the information that appears inside the Postman app as well as in the docs (for example descriptions on the collection, requests, and parameters).

If your collection contains lots of requests, consider grouping them into folders to make the documentation and imported templates easier to navigate.

Check your docs on the web

When you publish documentation for a Postman collection, you will author the content inside the Postman app in Markdown, but consumers will view it in the web browser as HTML. For this reason, it's essential to read through your docs in the browser to get a feel for how they will walk developers through the process of using your API, and to ensure your collection information is rendering as expected (this is particularly important if you're using variables to populate some of the content).

Tailor your examples

The sample code section in your docs will play a significant role in how effectively developers are able to onboard with your API. Your collection examples will automatically populate in the docs code, so it's worth taking the time to ensure that the examples contain readable, prototypical usage of your API endpoints.

Add contextual material

When developers attempt to learn how to integrate with a third-party API, they need to understand more than just what each endpoint receives and returns. By introducing your API with contextual material explaining its purpose at a high level, and outlining how the different requests fit together to build client applications, you will help new users get off to a more effective start. Ideally include quickstart information that lets developers make a request to your API as soon as possible.

If your API requires authentication, make sure you include instructions explaining what developers need to do to acquire and use credentials. Other top level info such as rate limits, content types, or settings that apply across endpoints can appear in your collection description so that they render at the top of your documentation page.

Complete your profile

When you publish to the API Network, potential users will initially see your team profile, with APIs listed under it. Taking the time to fill out your team profile gives consumers a clear sense of who a collection is published by—helping them to decide whether to try it out or not. You can include a team name, description, logo, and custom URL.

Complete your API listing

Your API listing in the network should provide the information developers need to know in order to decide whether they want to try the API out or not. Try to choose a descriptive name that conveys the purpose of your API without users having to click it to find out more detail. In your description, try to include an overview of what the API does, with enough detail for consumers to figure out whether it's likely to fit their use case. You can include a name, summary, description, and categories that will determine how your API is listed when users browse the network.

Sample API Network listings

The API Network includes lots of effective listings you can use for inspiration when building your own. Check out the following notable examples: