Files
Django_TasksApp/main/API.md
T

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'
```