Document your API like a pro: Postman Collection best practices

Postman Collections are executable documentation for APIs and API workflows, designed for sharing. They let you organize multiple API requests in a single folder and subfolders and help you collaborate with teammates to create and design your API. You can use them to create requests and examples of your API’s responses, run collections, share your collection, and use collections in your development workflows.

But a Postman Collection is only useful when it’s, well, easy to use. And great documentation makes that possible. Strong collection documentation provides thorough details about how to get started using your API, what to expect when using it, and how to use each endpoint. Making sure to completely document your collection also ensures that users are well-informed and helps eliminate user frustration.

In a previous blog post, “Measure your Postman Collection’s quality with the Postman API and Spectral rules,” Postman Technical Product Manager David Espi Hernandez provided a wonderful tool to automate the evaluation of Postman Collections against a collection quality ruleset. In this latest post, we’ll go over how you can take documenting your collections further by providing your users with all the information they need to be thoroughly informed and successful when using your API.

Use templates to get started

Not sure how to begin documenting your collection? Uncertain about how you want to structure your collection’s documentation? Postman’s collection templates provide many different templates to help get you started—including an API documentation template:

When you create a new collection, select this template. All you need to do is update the template with your API’s information and details in the fields provided.

As you consider what to include and how you document your API in your Postman Collection, follow the following best practices to ensure your users get the most out of it—which will lead to significantly greater API adoption.

6 basic but essential documentation concepts

1. Keep it simple

When documenting an API, a good rule to follow is to “keep it simple.” Document your API in a style that is precise and literal. It keeps your user’s attention from being distracted by unnecessary information and helps them quickly find what they are looking for.

This overarching tip is also really important for supporting users who may be non-native speakers of your documentation’s language—which is an increasing factor to consider in today’s growing, global API community. These users may rely on translation tools to help them read your documentation. Avoiding jargon, abbreviations, or colloquialisms in your documentation also makes it easier for users to translate your documentation into other languages.

Try to avoid writing overly complicated, long, and complex sentences; break them up if you need to. For paragraphs, keep them at about five sentences per paragraph. You can make use of free online Flesch-Kincaid readability assessment tools like Hemingway Editor to gauge your writing’s complexity. Generally, a score of 8 to 10 is considered a good score and easily readable. Consider revising anything that is higher if possible.

2. Use style guides

Create or adopt a style guide to follow, such as Google’s developer documentation or Microsoft’s developer content style guide. This will help frame your documentation’s tone and voice with your brand to your developer audience. Guides are valuable because they keep your documentation aligned with a specific style and—most importantly—consistent. Inconsistencies can be confusing to users.

3. Have consistent formatting and style

Make information stand out and easy to scan with the use of headers, bullets, bold, italics, and code formatting. Use the Postman editor or classic Markdown editor to help you visualize your formatting when documenting your API.

Keep your format styling consistent throughout your documentation. Using different format styles, like inconsistent writing tones or formatting (such as bold for files in one request, then code format in another request), can be confusing or disrupting to users.

4. Write for a wide audience

While you may be writing for a developer audience, you should always try to keep your documentation clear and easy to follow for even the most novice developer. This is useful to less-experienced developers or other users who want to understand your API. Never just assume that your audience is full of developer experts!

5. Recruit reviewers

Most importantly, proofreading and having others review your work is guaranteed to ensure that you publish great documentation. Reach out to different types of users, such as non-developers, for their input. They can help you find gaps in your documentation that a developer may miss, or point out where something is too complex, wordy, or confusing.

6. Descriptions are important

At the top level of a collection, it’s always best practice to create a thorough Overview section to set your API users’ expectations and help guide them. Consider that your API user’s journey starts here. This is where you can inform them about how they can use your API. Provide specific details, such as authentication or rate limits, expected response formats, or details about specific headers. If you’re not sure where to start or how to structure your documentation, use Postman’s API documentation to get started.

Be thorough in your collection’s overview—the more informed a user is, the more likely they are to use your API. Provide too little—or no information—and a user is more likely to give up.

You can use the collection overview to document details about the collection’s tests or variables, like information on how users can leverage that information, or link to an environment that the collection uses to quickly guide users to additional resources. You can even provide users with contact info for you or your support team to help them directly with your API.

Pro Tip: Not sure where to begin? Use our AI assistant, Postbot, to generate a description and tailor it to your style and tone

5 tips to document all of your API’s requests

Consider the following structure for your API request’s documentation:

1. Describe what the request does

Even if it’s just a sentence or two that describes what a request does, such as “Gets the user’s information” for a GET request, it’s still useful information. It lets users know what to expect from your API, no matter how simple it is. Any information is better than no information at all. You can’t assume that all users will know how to use your API.

2. Document request body properties

For PUT and POST-type APIs, it’s good practice to document the request body properties in your request’s documentation. Providing request body property types, such as object or string, as well as what the property is and what users can expect them to do, will help users better understand how to use your API. If a property only accepts specific values, list them.

3. Make important information stand out

For important information that your users should know about the request, precede the information with a lead-in statement like Note or Important or Pro Tip. This helps ensure that your information is clearly visible to users and doesn’t get overlooked.

4. Describe parameters

Postman makes it easy to document path and query parameters. You should always include a description about the parameter. This tells a user what to expect when they use it.

• If it’s a required parameter, state that it’s required.
• If the parameter accepts only specific values, list those values in the description.

Provide the parameter’s type value. For example, if it is type: string, mention this somewhere in the description. You can provide this information in the Value field in the Params tab:

5. Include deprecations

If you’ve deprecated a request, you should note it in the documentation. It can be a simple statement in your request’s description, such as This endpoint is deprecated. You can also rename the request to include “Deprecated” in its name for further visibility:

When possible, it’s also good practice to:

• Include a reference or link to the request that replaced the deprecated request. This guides users to the most up-to-date information and helps them quickly accomplish what they want to do with the request.
• Mention any versions that the deprecation applies to. For example, This endpoint is deprecated in API v2 and higher.
• Don’t simply delete or remove deprecated requests. You need to give your users time to see and adjust to the changes. Consider leaving deprecated requests in place for at least a year.

Provide response examples

Response examples give context and help users understand the request and response flow. At the very least, always provide an example of a successful response. However, providing multiple examples—such as 4XX and 5XX responses—can help users troubleshoot issues they may run into.

Describing the expected successful response in the request’s description can help users better understand the response payload. For example, add a brief summary of the properties in the response, like:

“The response includes information such as the user’s name, unique ID, the date of the user’s creation, and their email address.”

POST and PUT requests benefit from request body examples. It’s good practice to provide a request body that matches the type of response. For example, include an incorrect request body format if you are providing an error response example. Don’t just copy the successful response; the incorrect format provides users context to better understand what would result in the error response.

Share your collection

Once you’ve finished documenting your collection, publish it and share it with users! Consider sharing your API on the Postman Public API Network for greater visibility to users around the world. This enables Postman users to discover and consume your public APIs directly in Postman.

Don’t forget to register here to attend POST/CON 24, Postman’s biggest API conference ever: April 30 to May 1, 2024 in San Francisco.