Added behavior journal, adjusted layout, and added some colors
This commit is contained in:
1 parent
b1b89ad334
commit
3237cd7601
31 files changed
+2135
-275
No files matched your search
+46
-1
@@ -1,5 +1,30 @@
|
||||
# FlockPal API Reference
|
||||
|
||||
## Customer integration reference
|
||||
|
||||
The interactive customer API reference is available at **`/api/docs/`** on your
|
||||
FlockPal instance (locally, `http://localhost:5000/api/docs/`). Download the
|
||||
OpenAPI 3.0 specification at **`/api/openapi.json`**. There is also a link in
|
||||
Settings → Integration tokens.
|
||||
|
||||
Create an integration token in Settings, then paste it into Swagger's **Authorize**
|
||||
dialog without the `Bearer` prefix. Use `read_only` for reading or `read_write`
|
||||
for changes. Tokens apply to their originating workspace and the creator's
|
||||
current membership permissions. Swagger's **Try it out** makes real API requests.
|
||||
|
||||
The customer reference covers integration-token endpoints only. The broader
|
||||
application reference below also includes browser-session and administrative APIs.
|
||||
|
||||
### Maintaining the interactive reference
|
||||
|
||||
- Request validators live in `backend/src/schemas.ts` and are shared with route handlers.
|
||||
- Customer operations are explicitly registered in `backend/src/docs/openapi.ts`.
|
||||
- Response models live in `backend/src/docs/responses.ts`; update them when serialized responses change.
|
||||
- `backend/src/docs/openapi.test.ts` validates OpenAPI, compares customer coverage against actual route middleware, and checks locally served Swagger assets and security headers.
|
||||
- Run `npm run build` and `npm test` in `backend` after changes.
|
||||
- The Zod-to-OpenAPI dependency is pinned to the Zod 3-compatible release; upgrade both together.
|
||||
|
||||
|
||||
This document describes the HTTP API currently implemented in `backend/src/app.ts`.
|
||||
|
||||
## Base URLs
|
||||
@@ -933,7 +958,7 @@ Possible errors:
|
||||
|
||||
#### `DELETE /api/birds/:birdId`
|
||||
|
||||
Requires auth with write access and role `owner`, `assistant`, or `caregiver`. Deletes a bird.
|
||||
Requires auth with write access and role `owner`, `assistant`, or `caregiver`. Removes the bird from its current flock without deleting its profile, photo, or care history. Bird-specific notes stay with the bird. Public sharing is disabled and pending transfers are revoked. Workspace audit logs and flock-wide notes remain in the source flock.
|
||||
|
||||
Response `204` with no body.
|
||||
|
||||
@@ -941,6 +966,22 @@ Possible errors:
|
||||
|
||||
- `404` if the bird does not exist in the active workspace
|
||||
|
||||
#### `GET /api/birds/unassigned-match?tagId=…`
|
||||
|
||||
Requires auth and role `owner`, `assistant`, or `caregiver`. Returns `{ "available": true }` only for an unassigned, non-memorialized bird whose band ID matches exactly after trimming and ignoring letter case. No profile, history, or former-flock details are disclosed. Blank/unknown IDs return `400`; partial IDs do not match.
|
||||
|
||||
#### `POST /api/birds/claim`
|
||||
|
||||
Requires auth with write access and role `owner`, `assistant`, or `caregiver`.
|
||||
|
||||
```json
|
||||
{ "tagId": "BAND-123", "confirmHistory": true }
|
||||
```
|
||||
|
||||
Returns `200` with `{ "bird": { ... }, "historyImported": true }`. Adds the existing unassigned bird to the current flock using its saved profile and history. The bird's ID and photo are preserved; bird-specific notes follow it. Public sharing remains disabled until explicitly enabled. Competing requests are serialized so only one flock can claim a bird.
|
||||
|
||||
Returns `400` without explicit history confirmation, or `409` if no matching unassigned bird remains. Creating a new profile via `POST /api/birds` with an unassigned bird's band ID returns `409` with code `bird_history_available` instead of duplicating or overwriting its profile.
|
||||
|
||||
### Weights
|
||||
|
||||
#### `GET /api/birds/:birdId/weights`
|
||||
@@ -1266,3 +1307,7 @@ curl -X POST http://localhost:5000/api/auth/magic-link/request \
|
||||
curl http://localhost:5000/api/auth/session \
|
||||
-H 'Authorization: Bearer YOUR_SESSION_TOKEN'
|
||||
```
|
||||
|
||||
### Behavior Journal
|
||||
|
||||
Behavior types and occurrences are available under `/birds/{birdId}/behavior-types` and `/birds/{birdId}/behaviors`. The interactive reference documents request/response schemas and permissions. See [Behavior Journal](BEHAVIOR_JOURNAL.md) for timestamp semantics, flock scoping, and isolated workflow tests.
|
||||
Reference in new issue
Block a user