In my previous article, Docs As Code: The Best Guide For Technical Writers, I talked about the concept of Docs-as-code and gave a deep dive into it.
Before starting as a Documentation Engineer, I didn't know much about API documentation. The take-home task I was given by the company was to document the endpoints of an API given to me. I took this journey and began learning about API documentation and the different tools for documenting API.
I will be sharing all that I have learned so far.
Why do you need API Documentation?
APIs (Application Programming Interfaces) play an important part in empowering software systems to communicate and interact effectively. Proper API documentation is needed for developers (or whoever will come across the documentation) to understand and utilize these APIs.
One of the tools that has become a favorite Postman.
Table of Contents
1. 1. What is Postman for API documentation?
1.1. Why Use Postman for API Documentation?
2. 2. How to Set Up Postman For API Documentation
2.2. Steps to Install Postman for API Documentation
3. 3. Steps For Creating API Documentation in Postman
3.3. What is a Collection in Postman?
3.4. Step 1: Create a Collection
3.5. Step 2: Add Requests to Your Collection
3.6. Step 3: Document Each Request
3.7. Step 4: Generate and View Documentation
4. 4. Best Tips For Organizing Your Documentation in Postman
4.9. Use Environments in Postman
4.10. Use Variables in Postman
5. 5. Sharing and Collaborating in Postman
5.11. Share Collections
5.12. Use Team Workspaces
5.13. Commenting and Version Control in Postman
6. 6. Top 5 Best Practices for API Documentation
6.14. Be Clear and Concise
6.15. Include Examples
6.16. Keep It Up to Date
6.17. Use Descriptive Names
6.18. Utilize Postman Features
7. 7. Conclusion
1. What is Postman for API documentation?
Postman is a collaboration platform for API development. It simplifies each step of building an API and streamlines collaboration so that you can create better APIs—faster.
Why Should You Use Postman for API Documentation?
- User-Friendly Interface: Postman's intuitive interface makes it easy for developers of all skill levels to create, test, and document APIs.
- Comprehensive Features: From automated testing to monitoring and collaboration, Postman offers a wide range of features that enhance the API development process.
- Collaboration Tools: Teams can share collections, environments, and documentation, facilitating better collaboration and consistency.
2. How to Set Up Postman For API Documentation
To get started with Postman, you need to install the application on your computer. Postman is available for Windows, macOS, and Linux. You can download it from the Postman website.
Steps to Install Postman for API Documentation
- Download Postman: Visit the Postman website and download the appropriate version for your operating system.
- Install Postman: Follow the installation instructions specific to your OS.
- Sign Up/In: Once installed, open Postman and sign up for a new account or log in if you already have one.
3. Steps For Creating API Documentation in Postman
Creating API documentation in Postman involves a series of well-defined steps. Here's how you can do it:
What is a Collection in Postman?
A collection in Postman is a group of requests.
Step 1: Create a Collection in Postman
To create a collection:
- Click on the Collections tab in the sidebar.
- Click the New Collection button.
- Name your collection and add a description if needed.
Step 2: Add Requests to Your Collection in Postman
Within your collection, you can add individual API requests:
- Click on your collection to open it.
- Click Add a request.
- Name your request and specify the HTTP method (GET, POST, PUT, DELETE, etc.).
- Enter the API endpoint URL and any required parameters.
Step 3: Document Each Request
For each request, you can add detailed documentation:
- Click on a request to open it.
- Click on the Documentation tab.
- Add a description, including details about the endpoint, parameters, headers, and sample responses.
- Save your changes.
Step 4: Generate and View Documentation in Postman
- Go to your collection.
- Click the
...
(three dots) menu next to your collection. - Select
View Documentation
. This will open the documentation view within Postman.
For a shareable web version, you need to publish the documentation.
4. Top 3 Tips For API Documentation in Postman
Organizing your API documentation is the best thing to do. This will aid clarity and usability. Thankfully, Postman provides several features to help you keep your documentation well-structured:
Use Folders in Postman
Folders allow you to group related requests within a collection. To create a folder:
- Right-click on your collection.
- Select Add Folder.
- Name your folder and add requests to it.
Use Environments in Postman
Environments enable you to manage different sets of variables. For instance, you might have different environments for development, staging, and production. To create an environment:
- Click on the Environments tab in the sidebar.
- Click Add.
- Define your variables and save the environment.
Use Variables in Postman
Variables can be used to store values like URLs, tokens, or any other data that may change. This makes your requests reusable and easier to manage. To use variables:
- Define them in an environment.
- Reference them in your requests using the
{{variable_name}}
syntax.
5. How to Share and Collaborate for API Documentation in Postman
Postman excels in enabling team collaboration. Here are some ways you can share and collaborate on your API documentation:
Share Collections
You can share collections with your team:
- Click on your collection.
- Click the Share button.
- Choose how you want to share (via link, in a team workspace, etc.).
Use Team Workspaces
Team workspaces allow multiple users to collaborate in real-time. To create a team workspace:
- Click on your workspace name at the top left.
- Select Create Workspace.
- Invite your team members.
Commenting and Version Control in Postman
Postman supports commenting on requests and tracking changes, ensuring that everyone stays on the same page.
6. Top 5 Best Practices for API Documentation in Postman
To make the most of Postman for API documentation, consider the following best practices:
Be Clear and Concise
Ensure your documentation is easy to understand. Use clear language and avoid unnecessary jargon.
Include Examples
Provide examples of requests and responses to help users understand how to use the API.
Keep It Up to Date
Regularly update your documentation to reflect any changes in the API.
Use Descriptive Names
Name your collections, requests, and variables descriptively to make it easier for others to understand their purpose.
Utilize Postman Features
Take advantage of Postman's features, such as mock servers, monitors, and automated testing, to enhance your API documentation.
7. Conclusion
In conclusion, Postman is an incredibly powerful tool for API documentation. Its user-friendly interface, comprehensive features, and robust collaboration tools make it an ideal choice for developers and teams. By following the steps and best practices outlined in this guide, you can create clear, concise, and effective API documentation that will greatly benefit your API users.
Whether you are a solo developer or part of a larger team, leveraging Postman for API documentation can streamline your development process and improve the overall quality of your APIs.
Let's connect on LinkedIn! ❤
Top comments (29)
Be aware, postman copies your project data to their cloud where they will pinky swear keep it safe and private. They've changed their product to be so aggressive about sending themselves your data that it's easy for their product to cause a compromise. Ever since they made these changes, I'd not want to ever enter live or test credentials into their software.
We recently had a dev at an integration shop we hired accidentally publish API keys and non public api specs to a postman public web project, because they didn't realize postman was putting all their work online.
We don't recommend that any users hardcode any tokens or sensitive data in there Workspaces or the elements within them, there is messaging and warning in a number of places to discourage users from doing this.
Ensure that you use variables and place data that you don't want to sync, only in the current values of the variable.
We recently introduced the Postman Vault which is available to all users, to locally store encrypted sensitive data. These are only stored on your machine.
learning.postman.com/docs/sending-...
We also announced changes to enhance the security of data that can be made public by users, we already had the secret scanner in place that alerts users of sensitive data in Public Workspaces but now these are automatically delisted and removed from the Public API Network. More information about the other changes can be found here:
blog.postman.com/public-api-networ...
If users prefer a lightweight version of Postman which can be used offline and locally, we have the Lightweight API Client:
learning.postman.com/docs/getting-...
Oh wow. I'm hearing that a lot of people actually don't like using Postman. It's very interesting to find out.
I am using simple application Bruno usebruno.com
The app is much easier but very similar as Postman. You can simply keep every collection/request/scripts/... settings under version control.
Okay!! I'd check it out ASAP. Thank you for sharing.
If you'd like to try an open source { free } alternative to test APIs, try Hoppscotch - API request builder for web : hoppscotch.io
hoppscotch / hoppscotch
Open source API development ecosystem - https://hoppscotch.io (open-source alternative to Postman, Insomnia)
I don't recommend hoppscotch because it doesn't support git integration, managing collections as files, or self-hosted logins. Try bruno instead.
We're working on implementing Git friendly, file-based workspaces. Stay tuned for the next couple of releases!
I'd definitely try out hoppscotch and let you know what I think.
said were going to improve the desktop app in Q1 2024, but now it's Q3.
Hmm. Okay. I'd take a look at that
I hate Postman. It has so many annoying bugs and its interface is flooded with all the unnecessary bullshit. I use it only for GraphQL APIs. My personal favorite API client is Insomnia, though it's bad for GraphQL yet.
If all you need is a GraphQL client to build requests and test your endpoints, you could just use the Lightweight API Client instead.
learning.postman.com/docs/getting-...
If there are specific issues or bugs that you'd like to raise, you can do that here:
github.com/postmanlabs/postman-app...
We're always here to listen to constructive feedback and can improve what we offer to our users.
I'll check it out, thanks.
The lightweight client does not have environments and does not allow creating request collections. It's freaking useless. You added the cloud sync and forced users to use it by removing the core necessary features from the local (lightweight) version. Now it has 100500 bugs like:
And it's not the full list of what I found.
My feelings toward Postman are the same as to Internet Explorer 10 years ago. I wish it didn't exist, but unfortunately, there's no better GraphQL GUI at the moment.
Oh really? I haven't tried Insomnia yet!
I'd definitely do that.
Plus, Postman isn't so bad tbh.
Can it export documentation for your tests?
That's what this article is about.
I don't document it because I didn't know about it :)
But I do create collections, workspaces, and variables, name the requests, and arrange them properly so it's easier to work with.
By the way, have you tried Hoppscotch? A lot of people have moved from Postman to that (except me) 😅
Oh really? I guess that's what I'm trying out next!
My plan is to use a lot of platforms and write about them so that others can learn as well.
Wonderful share @dumebii! This will be a lot of help when I'm writing out my backend methods and testing on Postman. I like how we can document as we go, and by the end of it- we have great documentation to reference and share! ❤
Yaaay. Awesome! 🥳
Great article, we heavily use this documentation feature.
I also recently discovered an open source tool that i am currently learning and experimenting with in my free time - FlowTestAI.
github.com/FlowTestAI/FlowTest
useflowtest.ai/
What i noticed was that this tool is very different from existing tools in the market as it takes an end to end API testing approach. Because this tools translates things into a visual graph, these end to end flows can potentially act as your live documentation.
Also it allows to create end to end API tests using natural language via LLMs which makes job for us QA people very easy as we don't have to read and understand openAPI specs anytime a new endpoints are released for testing
Oh wow. That's a whole lot.
I'd be checking it out and writing about it soon.
Thanks for sharing!
Great topic! You opened up discussion that introduced a line of API products supporting documentation and testing. As much as I like Postman, learning about these other products is really helpful.
Thank you so much! I'm glad you found this helpful.
apidog.com/
Postman alternative better than postman in terms of documentation
Oh really? I'd definitely check it out!
Awesome 👍😎
Thank you!