Skip to main content

postman-endpoint

When development adds or changes an HTTP endpoint, save it in Postman so the collection stays an accurate, runnable record of the API โ€” with a real example call and the response it returns. This is the Definition of Done step ยง4 for any API change.

The endpoint contract itself (DTO shape, status codes) is owned by contracts-schema. This skill is about recording the runnable example in Postman, not designing the contract.

Where things liveโ€‹

  • Organization R&D Postman workspace โ€” the single shared workspace. Add the request to the collection for the owning service; do not create personal forks for shared endpoints.
  • Postman MCP (when configured) โ€” use it to create/update the request, the example, and the environment. Otherwise do it in the Postman app and note that it was done.
  • Environment + Vault โ€” {{baseUrl}}, {{token}}, ids like {{organizationId}} come from the environment; secrets live in the Postman Vault. Never paste an API key, JWT, or OAuth secret into a committed file, the collection body, or chat.

Stepsโ€‹

1. Identify what changedโ€‹

List the endpoints the PR adds or changes: method + path (e.g. POST /api/organizations/{organizationId}/events/{eventId}/notifications/schedule). For an internal @MessagePattern RPC there is no HTTP surface โ€” record "RPC, no Postman entry" on the task and rely on the contract test instead.

2. Add / update the request in the collectionโ€‹

Place it under the owning service's collection folder. Use environment variables for the base URL, auth, and ids โ€” never hardcoded hosts or tokens. Set method, path, headers (Content-Type, Authorization: Bearer {{token}}), and a representative request body.

3. Save a response exampleโ€‹

Send the request against a working environment (local or sandbox) and save the returned response as a named example on the request โ€” status code + body. This is the "sample call โ†’ sample result" that makes the collection self-documenting. Capture the main success case; add notable error cases (e.g. 401, 422) where they clarify the contract. Strip any secret/PII from saved example bodies.

4. Make it runnable (verdict)โ€‹

Add a minimal test script (status code, key fields present) so the request passes under the Collection Runner / newman. A green run is a verdict with the same standing as test in the DoD; a red run blocks PR readiness.

5. Record it on the taskโ€‹

Note on the GitHub Issue / PR body which endpoints were added to Postman (collection + request name) so the Definition of Done ยง4 box is verifiable. A short markdown example (method, URL, headers, body, expected response) in the PR body is a good lightweight mirror for reviewers.

Boundariesโ€‹

  • Never commits or pastes secrets. Environment + Vault only; scrub saved example bodies.
  • Records, does not design. Endpoint shape/validation is contracts-schema + backend-developer; this skill captures the runnable example.
  • Shared collection, not a personal fork, for endpoints other people consume.

Cross-referencesโ€‹