shoc-backend/postman/README.md

SeaHaven Dev Postman starter

A small, versioned Postman starter for the SeaHaven backend dev API.

• The live OpenAPI document ({{baseUrl}}/swagger/v1/swagger.json) is the complete source of truth for routes and schemas. This committed collection is a curated starter — it is not a generated copy of the full API surface.
• Dev only. Never point these requests at any other environment.

Files

File	Purpose
SeaHaven-Dev.postman_collection.json	Starter collection: setup requests plus safe read-only requests
SeaHaven-Dev.postman_environment.json	Dev environment: baseUrl plus empty secret username / password / token

Getting started

1. Import order — collection first, then environment:
   1. Postman → Import → postman/SeaHaven-Dev.postman_collection.json
   2. Postman → Import → postman/SeaHaven-Dev.postman_environment.json
2. Select the environment — pick SeaHaven - Dev in the environment picker (top right of Postman).
3. Fill credentials locally — open the environment and enter values for username and password. They ship empty and marked secret on purpose; keep them local to your Postman workspace.
4. Run login — run Authentication - Login in the Setup folder once. A successful (200) response captures the bearer token automatically. Every login attempt clears the previous token value without deleting the variable, so a failed login cannot leave stale authentication active.
5. Use the safe reads — everything in the Safe reads folder inherits the collection-level Bearer {{token}} auth, so no extra setup is needed.

Token capture behavior

The login test script stores the returned bearer token only in the environment variable token via pm.environment.set("token", token). It never writes collection or global variables and never prints credentials or tokens to the Postman console. The pre-request script skips the request and stops with a clear message if username or password is empty.

Clearing the token: open Environments → SeaHaven - Dev, clear the token value (or use the environment reset), and save. Do this before sharing screens, exporting, or switching machines.

Safety rules

• Keep populated username, password, and token values local. Never mark them shared, export them, or commit them.
• Never save dev response bodies as collection examples or commit them.
• Full API surface: in Postman, choose Import → Link and paste https://api.dev.seahaven.com/swagger/v1/swagger.json. The Swagger - OpenAPI document request is also available to check that the contract is reachable.
• Canonical routes: some legacy aliases may still resolve on dev, but this collection sticks to canonical routes — prefer those when adding requests.