postman

Postman Best Practices

Postman is our definitive tool for API development, testing, and documentation. Adhering to these guidelines ensures consistency, maintainability, and reliability across all our API interactions.

1. Code Organization and Structure

Organize your Postman collections like source code: structured, versioned, and modular.

1.1 Collection Hierarchy

Mirror your API's resource structure with a clear folder hierarchy. Each folder should represent a logical API resource or module.

❌ BAD: Flat Collection

- My API
  - Create User
  - Get User by ID
  - Update Product
  - Delete Order

✅ GOOD: Structured Collection

- My API v1.0
  - Users
    - POST Create User
    - GET Get User by ID
    - PUT Update User
    - DELETE Delete User
  - Products
    - POST Create Product
    - GET Get Product by ID
    - PUT Update Product
    - DELETE Delete Product
  - Orders
    - POST Create Order
    - GET Get Order by ID
    - PUT Update Order
    - DELETE Delete Order

1.2 Request Naming

Use descriptive names for requests, including the HTTP method and the resource path.

❌ BAD: Vague Request Names

- Get User
- Update Product

✅ GOOD: Explicit Request Names

- GET /users/{id}
- PUT /products/{id}
- POST /auth/login

1.3 Variables Management

Leverage Postman variables (global, environment, collection) to avoid hardcoding and promote reusability.

• Global Variables: For non-sensitive, truly global data (e.g., common utility functions). Use sparingly.
• Environment Variables: For environment-specific configurations (e.g., BASE_URL, AUTH_TOKEN, API_KEY). Never commit sensitive data to source control.
• Collection Variables: For data specific to a collection (e.g., user_id, product_name) that might change during a test run but is not environment-specific.

Naming Convention:

• Environment Variables: UPPER_SNAKE_CASE (e.g., DEV_BASE_URL, PROD_AUTH_TOKEN)
• Collection/Local Variables: camelCase (e.g., userId, productName)