How to create and publish API documentation with Postman?
API stands for Application Programming Interface, which allows computers to talk to each other. The essence of API is the request and response communication between a client and a server. The client is the front-end application a user interacts with, while the server is the back-end logic and database operations. An API acts as an intermediary between a client and a server, enabling the exchange of data between the two. It allows the client to send requests for information to the server and for the server to return responses to those requests.
What is the API documentation?
API documentation is a technical content deliverable that guides the user on utilizing and integrating APIs effectively. It is a reference guide that includes all the details needed to use the API.
What is Postman?
Postman is an API platform for building and using APIs. Postman simplifies each step of the API lifecycle and streamlines collaboration so you can create better APIs faster. To get the latest version of the Postman desktop app, visit the download page and select Download for your platform. See the Postman installation and updates page for more information.
Steps to create API documentation using Postman.
Step 1: Create a new collection
Postman collection allows you to save your requests to be reused and shared anytime. It also lets you group your requests so that each API resource can act like a folder where you can save similar endpoints.
Let’s create a new collection.
As shown in the below image, click the + icon and provide a meaningful name for your collection.
To describe your collection, click the file icon inside the new collection and open the documentation section. Here, you can give an overview of your collection’s content and the purpose of the documentation.
Step 2: Add requests
Now we can add different requests to the collection we created.
An API request is a request made to a specific application programming interface (API) by a client in order to retrieve or manipulate data. To make an API request, a client will send a request to the API server, typically using the HTTP protocol. The request will specify the type of action to be performed (such as retrieving data or modifying data), as well as any necessary parameters or data required to complete the request. The API server will then process the request and send a response back to the client, which may include the requested data or a status code indicating the success or failure of the request.
The good thing about Postman is that we can use it to test our requests before adding them to the documentation. To add a request, click Add a request link inside your collection.
It will take you to the section where you can enter the API endpoint and test the API.
An API endpoint is a specific URL that represents an access point for retrieving or modifying data that is stored on a server. For example, if a company has a website that allows users to search for flights, they may have an API endpoint that allows other software systems to access the flight search functionality of the website. Other systems can then use this endpoint to search for flights and retrieve flight information without having to build their own flight search functionality from scratch.
I’m using Reqres, a free online REST API, to retrieve the data.
Add GET request
First, let’s add a GET request to our collection.
The GET request is typically used to retrieve information from a server without modifying any data. It is a read-only request, and it should not have any side effects on the server or the resource being accessed. This means that a GET request should not create, update, or delete any data on the server.
Select GET from the dropdown list and enter the URL https://reqres.in/api/users?page=2
Click Send to send the request, and you can check the response below. The HTTP status code 200 OK is a standard response code indicating that the request was successful and the requested information was returned.
On the right side, you can enter a description for the GET request.
Add POST request
Let’s try a POST request.
POST requests are used to submit data to a server for processing and are often used when submitting a form on a web page. They differ from GET requests, which are used to retrieve data from a server, in that they send data to the server rather than requesting data from it.
We need key-value pairs to send a POST request. In this example, I’m going to create a new user, and for that, I’m using the name and job as the keys. In Postman, after entering the URL, we must specify the key-value pairs inside the Body.
The HTTP status code 201 Created indicates that the request to create a new resource has been successful and that the new resource has been created as a result.
Add PUT request
The PUT request is similar to POST, but it is a request to modify or update a resource on a server. The PUT method is used to completely replace a resource with new data, while the PATCH method is used to update only specific fields of a resource.
In the following example, I update the name and the job role of the user with ID number 2.
Add DELETE request
A DELETE request is used to delete a resource at a specified endpoint. In this example, I’m going to delete the user at the endpoint api.example.com/users/123.
In the context of a DELETE request, a 204 No Content response typically indicates that the resource has been successfully deleted and that there is no additional content to send back to the client.
Don’t forget to click Save after adding each request to your collection.
Publish API documentation using Postman
Now that we have added our sample requests and descriptions to the collection, we are ready to publish our documentation online.
Click the three dots next to your collection and select View documentation.
You will see the entire documentation. Click Publish to publish the documentation.
This will direct you to the Postman website. There you can change the default styling of your documentation and simply click the Publish button. The next page will provide you with the URL for your documentation.
This is the final outcome of the API documentation we created using Postman.
Use the following link to access the API documentation we just created. You can try it on Postman by clicking the Run in Postman button.
Thanks for reading and creating the API documentation with me! Feel free to add your thoughts down below in the comments section.
