A developer spends up to 3 hours per day checking endpoints against outdated documentation. A Postman (software) Collection reduces this to 15 minutes. We created a collection for a project with 200+ endpoints: after deployment, the number of bugs per release dropped by 40%. Our experience — 10+ years in development and 50+ API documentation projects. Average budget savings on testing — 30%, ROI less than 3 months. Get a consultation on your API — contact us.
How a Postman Collection Solves the Problem of Outdated Documentation
Outdated documentation is a common pain: endpoints change, parameters become obsolete, and developers spend hours debugging. A Postman Collection is a living document: you immediately execute requests, see real responses, and automatically check statuses. We guarantee that after delivery the collection will match the API — we use auto tests that validate every endpoint. A collection is a set of saved requests organized into folders.
Structure and Key Elements — Documenting API with Postman
Example collection structure
{ "info": { "name": "MyApp API", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" }, "variable": [ { "key": "base_url", "value": "https://api.example.com/v1" }, { "key": "token", "value": "" } ], "item": [ { "name": "Auth", "item": [ { "name": "Login", "request": { "method": "POST", "url": "{{base_url}}/auth/login", "header": [{ "key": "Content-Type", "value": "application/json" }], "body": { "mode": "raw", "raw": "{\"email\": \"[email protected]\", \"password\": \"secret\"}" } }, "event": [{ "listen": "test", "script": { "exec": [ "pm.test('Status 200', () => pm.response.to.have.status(200));", "const json = pm.response.json();", "pm.collectionVariables.set('token', json.data.token);" ] } }] } ] } ] } pm.collectionVariables.set — key pattern: the login test automatically saves the token, all subsequent requests use {{token}} in the Authorization header.
What Elements Make a Collection a Living Document?
Environments — Different Environments
{ "name": "Production", "values": [ { "key": "base_url", "value": "https://api.example.com/v1", "enabled": true }, { "key": "token", "value": "", "enabled": true } ] } Separate files env.development.json, env.staging.json, env.production.json — switched in Postman via dropdown. Templates without values are committed to the repository, files with secrets are not. For sensitive data, use CI system variables instead of storing them in the collection.
Pre‑request Scripts and Auto‑tests
Pre‑request scripts run before each request. Example — automatic token refresh:
const tokenExpiry = pm.collectionVariables.get('token_expiry'); if (!tokenExpiry || Date.now() > parseInt(tokenExpiry)) { pm.sendRequest({ url: pm.variables.get('base_url') + '/auth/refresh', method: 'POST', header: { 'Content-Type': 'application/json' }, body: { mode: 'raw', raw: JSON.stringify({ refresh_token: pm.collectionVariables.get('refresh_token') }) } }, (err, res) => { pm.collectionVariables.set('token', res.json().data.access_token); pm.collectionVariables.set('token_expiry', Date.now() + 3600000); }); } Such a script ensures the token is always up‑to‑date — even during long testing sessions.
What Mistakes Are Made When Creating a Postman Collection?
- Missing environment variables — you'll have to change URL in every request.
- No pre‑request scripts for token refresh — tests will fail after session expiration.
- Tests only check status code — add JSON schema validation using
pm.response.to.have.jsonSchema. - Collection not versioned — store it in Git alongside code.
- Newman not configured in CI — tests don't run automatically after deployment.
What Is Included in Turnkey API Documentation?
We provide:
- Ready‑made Postman Collection (structure, variables, example responses).
- Environments for all environments (dev/staging/production).
- A set of auto‑tests with status and response schema checks.
- Pre‑request scripts for automatic authentication.
- Integration with CI via Newman (GitHub Actions, GitLab CI).
- Publication of documentation on Postman API Network.
- Team training on working with the collection.
Order development of a Postman Collection and get up‑to‑date documentation with auto‑tests.
Comparison: Postman Collection vs OpenAPI
| Criterion | Postman Collection | OpenAPI |
|---|---|---|
| Purpose | Manual testing and executing requests | Describing API structure |
| Format | JSON (Collection v2.1) | YAML/JSON (OpenAPI 3.0) |
| Testing | Built‑in tests pm.test |
Requires external tools |
| CI/CD | Newman | Parsers (Swagger, Prism) |
| Documentation | Interactive, with ability to send requests | Static, for reading |
Postman Collection is better suited for quick testing and debugging, especially in team work. However, OpenAPI is useful for generating clients and servers.
Process and Timeline
| Stage | Duration |
|---|---|
| API audit — studying endpoints, response types, authentication schemes | 0.5 day |
| Collection design — grouping requests, defining variables and tests | 0.5 day |
| Creation — writing structure, pre‑request scripts, tests | 1 day per 20–30 endpoints |
| Testing — running the collection, fixing errors | 0.5 day |
| Integration — setting up Newman in CI, publishing documentation | 1 day |
Timeline: basic collection (20–30 endpoints) — 1–2 days. With integration and publication — 1 additional day. Exact timeline calculated after audit.
Step‑by‑Step Guide for Setting Up Newman in CI
- Install Newman globally:
npm install -g newman. - Create a
newman-run.jsfile with commands to run. - In CI config (GitHub Actions) add a step:
- name: Run API Tests run: | newman run collection.json \ --environment env.ci.json \ --bail failure - For reports, use
--reporters cli,json. - Schedule a run after each deployment.
--bail failure stops the run on the first error — convenient for smoke tests after deployment.
Why Choose Us?
Over 10 years of experience in API development and 50+ documentation projects. We guarantee the collection is up‑to‑date and ready for immediate use. Investment in creating a Postman Collection pays off: average budget savings on testing is 30%. Get a consultation on your API — contact us.