48 lines
5.1 KiB
Markdown
48 lines
5.1 KiB
Markdown
# TaskNest Food and Kitchen API v1
|
|
|
|
The API is intended for a future thin MCP adapter. It is available under `/api/v1/`; machine-readable OpenAPI 3.1 is at `/api/v1/schema/`. No MCP server or interactive production API UI is included.
|
|
|
|
## Authentication and permissions
|
|
|
|
Create a personal token in Settings → API access. The full `tn_...` token is shown once. Send it as `Authorization: Bearer <token>`. A token identifies its owner; API requests do not accept a user identifier. Tokens can have `food:read`, `food:write`, `inventory:read`, and `inventory:write`. A missing, invalid, revoked, or expired token returns HTTP 401. A missing scope returns HTTP 403. The token management screen supports optional expiry and revocation. HTTPS is required in deployment to protect bearer tokens in transit.
|
|
|
|
Each resource lookup filters by the token owner. An unknown UUID and another user's UUID both return 404. The API does not use session authentication, and its bearer-token views are CSRF exempt. Default Django CORS policy does not grant cross-origin browser access. Do not log `Authorization` headers.
|
|
|
|
## Endpoints
|
|
|
|
| Method | Route | Scope | Purpose |
|
|
| --- | --- | --- | --- |
|
|
| GET | `/food/today/` | `food:read` | User-local date, entries grouped by meal, seven daily totals, and existing goals |
|
|
| GET | `/food/products/?search=&limit=30&offset=0` | `food:read` | Own products, nutrition per 100, and portions; no `raw_data` |
|
|
| POST | `/food/log/` | `food:write` | Create from an owned `product_id` or manual snapshot |
|
|
| GET/PATCH/DELETE | `/food/log/{id}/` | read/write | Own log entry |
|
|
| POST | `/food/log/{id}/attachments/` | `food:write` | Multipart image upload to an owned entry |
|
|
| GET | `/food/attachments/{id}/file/` | `food:read` | Authenticated image retrieval |
|
|
| DELETE | `/food/attachments/{id}/` | `food:write` | Delete an owned image |
|
|
| GET/POST | `/kitchen/items/` | read/write | Search/list or create inventory item |
|
|
| GET/PATCH/DELETE | `/kitchen/items/{id}/` | read/write | Own inventory item |
|
|
|
|
Collection responses use `count`, `limit`, `offset`, and `results`. The default limit is 30 and maximum is 100; `offset` is capped at 10,000. Product and inventory search checks name, brand, and barcode; inventory search also checks location and category. `GET /food/today/` is naturally bounded by one day.
|
|
|
|
JSON decimal values are strings to preserve precision. For food creation, send `meal`, positive decimal `amount`, and `unit` (`g` or `ml`). With `product_id`, nutrition and name snapshots are calculated from that owned product using the same service as the web UI, and the unit must match its basis. Without a product, send `product_name` and optional `brand`, `barcode`, `portion_label`, and nutrition totals (`calories_kcal`, `carbohydrates_g`, `protein_g`, `fat_g`, `fibre_g`, `sugars_g`, `salt_g`). Manual entries are snapshot-only, so repeat estimates do not create duplicate products. `date` defaults to the user's saved local time zone date; an explicit ISO date and optional time can be supplied. API entries have `created_via: api`, separate from their nutrition `source`.
|
|
|
|
Inventory creation requires an owned product UUID, positive integer `quantity`, and a location name. Optional fields are `category`, `notes`, `opened`, and `best_before`. Location and category names reuse the application's owned lookup records. There is no invented inventory unit: the existing model counts whole items. DELETE removes the item, matching the API operation; the web inventory still has its separate archive behavior.
|
|
|
|
For attachment upload, send multipart `image` and optional `caption`. JPEG, PNG, and WebP are accepted after decoding and format/MIME checks. The file limit is 5 MiB and the pixel limit is 25 million. Images are stored under `main/private_media/`, which has no public media URL; download requires `food:read` and ownership of the parent entry. Filenames on disk are random. The original filename is metadata only.
|
|
|
|
POST creation routes accept an optional `Idempotency-Key` header. Repeating the same token, route, key, and body returns the stored result and creates no second record. Reusing a key with a different body or route returns 409. Keys are per token. JSON errors use `{"error":{"code":"...","message":"..."}}`; validation may include `details`. Common codes include `invalid_token`, `expired_token`, `insufficient_scope`, `entry_not_found`, `product_not_found`, `inventory_item_not_found`, `image_too_large`, and `unsupported_image_type`.
|
|
|
|
## Example requests
|
|
|
|
```sh
|
|
TOKEN='<token-shown-once-in-settings>'
|
|
curl -H "Authorization: Bearer $TOKEN" https://example.com/api/v1/food/today/
|
|
curl -H "Authorization: Bearer $TOKEN" 'https://example.com/api/v1/food/products/?search=pasta'
|
|
curl -X POST https://example.com/api/v1/food/log/ \
|
|
-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
|
|
-H 'Idempotency-Key: dinner-2026-10-07-1' \
|
|
-d '{"meal":"dinner","product_name":"Homemade satay","amount":"1","unit":"g","calories_kcal":"850"}'
|
|
curl -X POST https://example.com/api/v1/food/log/ENTRY_UUID/attachments/ \
|
|
-H "Authorization: Bearer $TOKEN" -F 'image=@meal.jpg;type=image/jpeg' -F 'caption=Dinner'
|
|
```
|