shoc-backend/postman

SeaHaven Dev Postman collection

This directory contains the complete SeaHaven backend dev API collection, generated from the live OpenAPI contract. The generated collection currently contains every operation in the contract (368 operations across 330 paths), including all documented parameters, request bodies, schemas, and response codes.

Files

File	Purpose
SeaHaven-Dev.postman_collection.json	Complete OpenAPI-derived Postman v2.1 collection, grouped by API tag
SeaHaven-Dev.postman_environment.json	Dev authentication environment with secret username, password, and reusable bearer token
../scripts/generate-postman-collection.mjs	Deterministic generator and coverage checker

Getting started

1. Import SeaHaven-Dev.postman_collection.json into Postman.
2. Import SeaHaven-Dev.postman_environment.json and select SeaHaven - Dev.
3. Enter the dev test account's username and password in the environment. They are empty and secret by default; never commit or share populated values.
4. Run Setup → Authentication - Login. The pre-request script clears any stale token, skips the request when either credential is missing, and never logs credentials. A successful response stores only its non-empty token field in the environment's token variable.
5. All generated API requests inherit collection-level Bearer {{token}} authentication. They reuse the captured token automatically.

Generated requests and examples

Every OpenAPI operation is included under its first alphabetically sorted tag. Path, query, and header parameters retain their required/optional status, schema hint, and description. JSON request bodies use recursively generated illustrative placeholders from local OpenAPI schemas; multipart requests use form-data fields and mark binary fields as files. These examples are not live records: replace placeholder values with a valid dev fixture before sending. No response bodies, credentials, tokens, or other dev data are stored in this repository.

The generated test script only checks that the response status is one of the codes documented by OpenAPI. It does not assume every operation returns 200.

Regenerate or check coverage

From the backend repository root:

node scripts/generate-postman-collection.mjs
node scripts/generate-postman-collection.mjs --check

The generator fetches https://api.dev.seahaven.com/swagger/v1/swagger.json, fails on a non-JSON/non-success response, and rewrites the collection and the empty-credential environment deterministically. --check compares the checked in collection with the current contract and verifies operation count, unique operation keys, request-body coverage, Bearer inheritance, and the explicit no-auth login exception.

Safety

This collection is dev-only. Do not point it at staging or production. Keep username, password, and token local to your Postman workspace; never mark them shared, export them, or commit them. Review every illustrative body and parameter before running a mutating request.