# Postman API Review Checklist

Use this checklist to review an API collection before sharing it with teammates, partners, or AI agents.

## 1. Collection Structure

- [ ] Collection name matches the product or API domain.
- [ ] Folders follow user or resource workflows.
- [ ] Requests are ordered from setup to common usage.
- [ ] Deprecated endpoints are separated or removed.
- [ ] Descriptions explain when and why to use each request.
- [ ] Examples are included for important success and error cases.

## 2. Authentication

- [ ] Auth type is documented.
- [ ] Token setup is explained.
- [ ] Environment variables are named clearly.
- [ ] Secrets are not committed or exported.
- [ ] Expired, missing, or invalid token behavior is documented.
- [ ] Permission scopes are listed.

## 3. Request Quality

- [ ] Paths are consistent.
- [ ] Query parameters are documented.
- [ ] Required and optional body fields are clear.
- [ ] Example bodies use realistic data.
- [ ] Idempotent and destructive requests are labeled.
- [ ] Pagination, filtering, and sorting are represented.

## 4. Response Quality

- [ ] Success responses include realistic examples.
- [ ] Error responses include common failure modes.
- [ ] Status codes are consistent.
- [ ] Response fields are documented or inferable.
- [ ] Empty-list responses are represented.
- [ ] Rate-limit responses are represented where relevant.

## 5. Tests

- [ ] Core requests assert expected status codes.
- [ ] Tests validate critical response fields.
- [ ] Tests avoid brittle assertions on unstable data.
- [ ] Setup requests store IDs or tokens for later requests.
- [ ] Negative tests cover missing auth and invalid input.
- [ ] Collection runs in a clean environment.

## 6. Agent-Ready Review

- [ ] Endpoint names are literal and predictable.
- [ ] Descriptions explain intent, not just mechanics.
- [ ] Examples include complete request and response pairs.
- [ ] Ambiguous fields have notes.
- [ ] Side effects are clearly labeled.
- [ ] Destructive actions have safe examples.
- [ ] Rate limits and retry behavior are documented.

## 7. Handoff

- [ ] Environment template is included.
- [ ] Base URL variables are clear for local, staging, and production.
- [ ] Collection can be run by a new teammate without tribal knowledge.
- [ ] Known limitations are documented.
- [ ] API docs and OpenAPI spec links are included.
- [ ] Owner and support path are named.