API Documentation With Postman
Tags: tutorial, api, postman, documentation
Published: 2020-11-16 13:20:07

> 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](https://www.postman.com/) 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](https://www.postman.com/). 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](https://dev.to/ebereplenty/hosting-a-nodejs-and-mongodb-app-on-heroku-38b8). We hosted it on [heroku](https://dashboard.heroku.com/apps). This is the [link](https://nodejs-mongodb-auth-app.herokuapp.com/).

Let's demonstrate this using the [register endpoint](https://nodejs-mongodb-auth-app.herokuapp.com/register)

### 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

```javascript

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

```
* Click the ``send`` button

* It should output a success response like so:

![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/mvg9qexqits61vtlob1a.JPG)

### 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](https://dev-to-uploads.s3.amazonaws.com/i/q7fvfckv5rn31p1si7z3.JPG)

* Change the request name to ``Register Endpoint``

![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/872qsmutp6xl7fmsxtbc.JPG)

* Enter the following in the ``Request Description``

```javascript

## 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

![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/dlqk8hp554tdp8mhj2ew.JPG)

* Now you have a button asking you to ``save to auth-tutorial``

![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/22iic5q6pw1diqvt6vm9.JPG)

* 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](https://dev-to-uploads.s3.amazonaws.com/i/2sypzhb1ktfc60wwhlc0.JPG)

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](https://dev-to-uploads.s3.amazonaws.com/i/u8gn3z0vajky82ik7wba.JPG)

* In the example tab, change the name to ``Register Endpoint Example`` 

![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/j8kx6fesxy1ioub77qn5.JPG)

* 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](https://dev-to-uploads.s3.amazonaws.com/i/k9jm67sa8noju1j6ohji.JPG)

* 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](https://dev-to-uploads.s3.amazonaws.com/i/tmaczxffhh69vtwelogm.JPG)

* 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](https://dev-to-uploads.s3.amazonaws.com/i/k95t2o9h5yx2h1gsqy55.JPG)

* Click on ``view web`` button. 

![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/yj17ix6unqaegzt7iguj.JPG)

* This redirects you to the browser showing you documented endpoint. You can check mine [here](https://documenter.getpostman.com/view/13495436/TVzVibja)

![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/6p5mg0s7u6us9hkk1yc8.JPG)

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

```javascript

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

```

Thank you for reading