Postman API Best Practices

Follow these conventions when creating, modifying, or reviewing APIs and OpenAPI specs.

Naming Conventions

• Use kebab-case for URL paths: /user-profiles, not /userProfiles or /user_profiles
• Use plural nouns for collection resources: /users, /orders, /products
• Use singular nouns for singleton resources: /users/{id}/profile
• Avoid verbs in paths. Use HTTP methods to convey action:
• POST /users (not /createUser)
• DELETE /orders/{id} (not /deleteOrder)
• Use camelCase for JSON properties: firstName, createdAt, userId
• Use consistent property naming across all endpoints

HTTP Method Semantics

| Method | Purpose | Idempotent | Success Code | |--------|---------|------------|--------------| | GET | Read resource(s) | Yes | 200 | | POST | Create resource | No | 201 | | PUT | Replace resource | Yes | 200 | | PATCH | Partial update | No | 200 | | DELETE | Remove resource | Yes | 204 |

OpenAPI Spec Standards

Every endpoint MUST have:

• operationId: Unique, camelCase identifier (e.g., getUser, createOrder)
• summary: Short description under 120 characters
• tags: At least one tag for grouping
• responses: At minimum, define the success response and common errors (400, 401, 404, 500)

Every parameter MUST have:

• type or schema with explicit type
• description: What the parameter does
• required: Explicitly set to true or false
• example: A realistic example value

Error Response Standard

All error responses should follow a consistent schema:

yaml
components:
  schemas:
    Error:
      type: object
      required: [error, code]
      properties:
        error:
          type: string
          description: Human-readable error message
        code:
          type: string
          description: Machine-readable error code
        details:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
              message:
                type: string

Define these error responses on every endpoint:

• 400: Validation error (with field-level details)
• 401: Authentication required
• 403: Insufficient permissions
• 404: Resource not found (on endpoints with path parameters)
• 429: Rate limit exceeded (with Retry-After header)
• 500: Internal server error

Pagination

List endpoints returning multiple items MUST support pagination:

yaml
parameters:
  - name: limit
    in: query
    schema:
      type: integer
      default: 20
      maximum: 100
  - name: offset
    in: query
    schema:
      type: integer
      default: 0

Response should include pagination metadata:

yaml
properties:
  data:
    type: array
    items: ...
  meta:
    type: object
    properties:
      total:
        type: integer
      limit:
        type: integer
      offset:
        type: integer

Authentication

• Document security schemes in the components.securitySchemes section
• Apply security globally or per-endpoint (never leave endpoints unprotected by accident)
• Use Bearer tokens or API keys in headers (not query parameters)
• Mark auth-related environment variables as secret type in Postman

Collection Organization

When creating Postman collections:

• Group endpoints by resource in folders (Users, Orders, Products)
• Include at least one example response per request
• Set collection-level auth (inherited by all requests)
• Use environment variables for base URL, tokens, and config
• Add pre-request scripts for auth token refresh if needed
• Add test scripts to validate response structure

Dates and Formats

• Use ISO 8601 for all dates: 2026-01-15T10:30:00Z
• Use format: date-time in schemas for datetime fields
• Use format: date for date-only fields
• Use format: email for email fields
• Use format: uri for URL fields

Versioning

• Include version in the API info: info.version: "1.0.0"
• Use URL path versioning (/v1/users) or header versioning
• Mark deprecated endpoints with deprecated: true
• Document migration path in the description of deprecated endpoints