70 lines
3.8 KiB
Markdown
70 lines
3.8 KiB
Markdown
# famapp HTTP API (v1)
|
|
|
|
REST JSON API under `/api/v1/`. Full OpenAPI spec is planned in task 87.3.
|
|
|
|
## Authentication
|
|
|
|
Every endpoint accepts **either**:
|
|
|
|
- Auth.js session cookie (browser login), or
|
|
- `Authorization: Bearer <household-api-token>` header
|
|
|
|
Unauthorized requests return `401` with `{ "error": "Unauthorized" }`.
|
|
|
|
Generate bearer tokens in **Settings → API tokens**.
|
|
|
|
## Endpoints (87.2)
|
|
|
|
### Calendars
|
|
|
|
| Method | Path | Description |
|
|
| ------ | ----------------------- | -------------------------------------------------------- |
|
|
| GET | `/api/v1/calendars` | List visible calendars |
|
|
| POST | `/api/v1/calendars` | Create calendar (`name`, optional `color`, `visibility`) |
|
|
| GET | `/api/v1/calendars/:id` | Get calendar |
|
|
| PATCH | `/api/v1/calendars/:id` | Update `name`, `visibility`, `color` |
|
|
| DELETE | `/api/v1/calendars/:id` | Delete calendar |
|
|
|
|
### Events
|
|
|
|
| Method | Path | Description |
|
|
| ------ | --------------------------------------- | --------------------------------------------------------------------- |
|
|
| GET | `/api/v1/events?from=&to=&calendarIds=` | List events in range (`calendarIds` = `all` or comma-separated UUIDs) |
|
|
| POST | `/api/v1/events` | Create event |
|
|
| GET | `/api/v1/events/:id` | Get event |
|
|
| PATCH | `/api/v1/events/:id` | Update event |
|
|
| DELETE | `/api/v1/events/:id` | Delete event |
|
|
|
|
### Lists
|
|
|
|
| Method | Path | Description |
|
|
| ------ | --------------------------------- | ------------------------------------------------------------- |
|
|
| GET | `/api/v1/lists?type=` | List lists (optional `type` filter, e.g. `shopping`, `tasks`) |
|
|
| POST | `/api/v1/lists` | Create list (`type`, `name`) |
|
|
| GET | `/api/v1/lists/:id` | Get list with items |
|
|
| PATCH | `/api/v1/lists/:id` | Update `name` or `archived` |
|
|
| DELETE | `/api/v1/lists/:id` | Archive list |
|
|
| GET | `/api/v1/lists/:id/items` | List items |
|
|
| POST | `/api/v1/lists/:id/items` | Add item |
|
|
| PATCH | `/api/v1/lists/:id/items/:itemId` | Update or toggle item (`done`) |
|
|
| DELETE | `/api/v1/lists/:id/items/:itemId` | Delete item |
|
|
|
|
### Notes
|
|
|
|
| Method | Path | Description |
|
|
| ------ | ------------------- | ----------- |
|
|
| GET | `/api/v1/notes` | List notes |
|
|
| POST | `/api/v1/notes` | Create note |
|
|
| GET | `/api/v1/notes/:id` | Get note |
|
|
| PATCH | `/api/v1/notes/:id` | Update note |
|
|
| DELETE | `/api/v1/notes/:id` | Delete note |
|
|
|
|
## Bearer token visibility
|
|
|
|
Bearer tokens see **household-visible calendars only** (private calendars are hidden). Mutations on calendars require ownership (session) or household visibility (bearer). Activity log records `actorId: null` for bearer mutations.
|
|
|
|
## Planned (87.3)
|
|
|
|
- Garden, bangs routes
|
|
- OpenAPI specification
|