cursor-plugin-postman-rule-postman-best-practices

name	cursor-plugin-postman-rule-postman-best-practices
description	API design best practices for Postman-managed APIs. Applied when working with OpenAPI specs, collections, and API code.
metadata	{"version":"0.1.0"}

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:

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:

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:

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