DEV Community

loading...

API Documentation With Postman

NJOKU SAMSON EBERE
I love providing solutions to real world problems. When I am not coding, I enjoy movies, hanging out and working out.
Updated on ・4 min read

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"
}

Enter fullscreen mode Exit fullscreen mode
  • Click the send button

  • It should output a success response like so:

Alt Text

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:

Alt Text

  • Change the request name to Register Endpoint

Alt Text

  • Enter the following in the Request Description

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

* No validation necessary

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

  • Save it by clicking the correct arrow

Alt Text

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

Alt Text

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

Alt Text

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)

Alt Text

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

Alt Text

  • 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:

Alt Text

  • 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.

Alt Text

  • 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

Alt Text

  • Click on view web button.

Alt Text

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

Alt Text

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"
}

Enter fullscreen mode Exit fullscreen mode

Thank you for reading

Discussion (0)