Request descriptions and documentation in Postman

Introduction

Request descriptions and documentation help explain what each API request does. This makes it easier for anyone using or testing the API to understand its purpose.

When sharing your API collection with teammates so they know what each request does.

When creating tests to ensure the API behaves as expected and you want clear notes.

When maintaining or updating APIs later and you need reminders of each request's role.

When onboarding new team members who need to learn the API quickly.

When generating automated API documentation for users or clients.

Syntax

Postman

In Postman, add a description to a request by clicking the 'Description' tab below the request URL field and typing your notes in Markdown or plain text.

Descriptions support Markdown formatting for better readability.

You can also add descriptions to collections and folders for overall context.

Examples

This simple description tells anyone what the GET request does.

Postman

GET https://api.example.com/users

Description:
Fetches a list of all users in the system.

Here, the description explains the purpose and what data is needed.

Postman

POST https://api.example.com/users

Description:
Creates a new user. Requires JSON body with 'name' and 'email' fields.

This helps testers know how the update works and what to expect.

Postman

PUT https://api.example.com/users/123

Description:
Updates user with ID 123. Only fields provided in the body will be changed.

Sample Program

This Postman request logs in a user. The description explains its purpose. The tests check that the login was successful and a token is returned.

Postman

POST https://api.example.com/login

Description:
Logs in a user with email and password.

Body (JSON):
{
  "email": "[e-mail]",
  "password": "securepass"
}

Tests:
pm.test("Status code is 200", function () {
  pm.response.to.have.status(200);
});

pm.test("Response has token", function () {
  pm.expect(pm.response.json()).to.have.property('token');
});

Important Notes

Good descriptions save time and reduce confusion during testing.

Keep descriptions clear and concise, avoid technical jargon if possible.

Update descriptions if the API changes to keep documentation accurate.

Summary

Descriptions explain what each API request does.

They help testers and developers understand and use the API correctly.

Use Postman's description tab to add clear, helpful notes to requests.