API Documentation With Postman

Have you ever written a bunch of code that you find difficult to recognize after a couple of weeks or months?

Have you spent ample time trying to figure out what a particular endpoint does and how to use it on the frontend?

Most experienced programmers will answer YES to those questions. So what was the problem? DOCUMENTATION!

Yes, Documentation is an important part of programming which is usually taught late or learnt the hard way - like we already pointed out above. Documentation can be within our code i.e. commenting our code or reporting our code or app in a separate document like the github readme. In this article, We are discussing how to do the latter using postman.

Postman is generally known as a tool that helps developers to test the effectiveness and efficiency of their API. However, it is more than that if you can check them out here. Postman helps you document your code for future purposes. How? That is what we will be answering in this article.

How to document API with Postman

To demonstrate this, we will be using the set of endpoints we built out in a previous series on authentication. We hosted it on heroku. This is the link.

Let's demonstrate this using the register endpoint

Make the request

• Go to your postman and create new request.
• Enter https://nodejs-mongodb-auth-app.herokuapp.com/register in the address bar.
• Change the request verb to POST.
• In the request body, enter the following

{
    "email": "samplenty@gmail.com",
    "password": "password"
}

• Click the send button

• It should output a success response like so:

Save the request and response

• Next to the Send button is a Save button. Click it. This will bring up a Save Request dialogue box like so:

• Change the request name to Register Endpoint

• Enter the following in the Request Description

## This request registers a user using **email** and **password**

* No validation necessary

• Below it, Click on the + Create Collection button to create a folder. Name it auth-tutorial

• Save it by clicking the correct arrow

• Now you have a button asking you to save to auth-tutorial

• Click it to Save that request. You should now see a set of collection by the left bar just as we created it

That's so cool!
But we can do even more to help other developers and our future self. Let's add an example of this request so that other developers and our future self can easily say that this is what we are expecting from that endpoint.

Add an Example

The example we are going to add is the request we just made. Check this out.

• Just before the response body, click on the save response link and select save as example. (This should open in a new tab)

• In the example tab, change the name to Register Endpoint Example

• Click on the Save Example to add the example to that endpoint

And that is it. We have documented that Endpoint. We can even access it anytime from the collections panel.

But how about if you want to share this documentation with others?

Let's do that

Share Your Documentation

• Go to the collections panel and click on the menu icon on the auth-tutorial collection. This should drop down a menu like so:

• Click on the Share Collection option. This should prompt you to sign in if you are not logged in or create account if you have not done so.

• Follow the process and sign in or create account. Then let's proceed

• Now click on the right arrow on the auth-tutorial collection. It should bring up a dialogue box

• Click on view web button.

• This redirects you to the browser showing you documented endpoint. You can check mine here

Congratulations!!! It is a great feet that you have reached

Conclusion

The importance of documentation cannot be over emphasized. We have see how important and how easy it can be to document our APIs.

Now that we have demonstrated with the register endpoint, see if you can try it with the login endpoint. See the data you need below:

endpoint url: https://nodejs-mongodb-auth-app.herokuapp.com/register
request body:

{
    "email": "samplenty@gmail.com",
    "password": "password"
}

Thank you for reading