mirror of
https://github.com/Sea-Haven-Industries/shoc-backend.git
synced 2026-10-01 08:43:15 +00:00
55 lines
2.8 KiB
Markdown
55 lines
2.8 KiB
Markdown
# 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.
|