update docs

README.md

@@ -55,6 +55,74 @@ X-API-Key: <your API_KEY>
 
 Missing/wrong key → `401`. `/`, `/health`, and `/docs` are open.
 
+## UI integration guide
+
+For a management portal the two primary resources are **Devices** (`/device`) and
+**VLANs** (`/vlan`). Everything else is lower-level raw-table access.
+
+**Base URL (staging):** `http://10.0.1.235:8000`
+**Every request:** header `X-API-Key: <API_KEY>` (except `/health`).
+**All bodies:** JSON with `Content-Type: application/json`.
+
+### Response shapes
+
+`GET /device/` — **paginated** envelope:
+
+```json
+{
+  "total": 4,
+  "limit": 50,
+  "offset": 0,
+  "items": [
+    { "mac_address": "AA-BB-CC-DD-EE-11", "group": "residents", "status": "paid",
+      "name": "Sara Ib", "phone": "9998887", "alias": "Living Room TV" }
+  ]
+}
+```
+
+`GET /device/{mac}`, `POST /device/add`, `POST /device/edit` — a single device object:
+
+```json
+{ "mac_address": "AA-BB-CC-DD-EE-11", "group": "residents", "status": "paid",
+  "name": "Sara Ib", "phone": "9998887", "alias": "Living Room TV" }
+```
+
+`GET /vlan/` — **plain array** (not paginated):
+
+```json
+[ { "alias": "residents", "vlanid": 51 }, { "alias": "staff", "vlanid": 55 } ]
+```
+
+- `status` is always one of `"new"`, `"paid"`, `"unpaid"`.
+- `group`, `name`, `phone`, `alias` may be `null` on older rows.
+- `DELETE` returns **`204` with an empty body** (nothing to parse).
+
+### Error shapes
+
+Application errors (`400`, `401`, `404`, `409`) return a **string** detail:
+
+```json
+{ "detail": "Device 'AA-BB-CC-DD-EE-11' already exists" }
+```
+
+Validation errors (`422`, bad/missing fields) return a FastAPI **array** detail:
+
+```json
+{ "detail": [ { "type": "missing", "loc": ["body","phone"], "msg": "Field required" } ] }
+```
+
+So in the UI: read `detail` directly when it's a string; when it's an array, join
+each entry's `msg` (and `loc`) for field-level messages.
+
+### Typical portal flows
+
+- **Provision a device:** `POST /device/add` with `mac_address`, `group` (an
+  existing VLAN alias), `name`, `phone`, optional `alias`. Handle `400` (group
+  missing), `409` (MAC exists), `422` (bad MAC / missing name·phone).
+- **Change plan state:** `POST /device/edit` `{mac_address, status}`.
+- **Move to another VLAN:** `POST /device/edit` `{mac_address, group}`.
+- **Populate a VLAN dropdown:** `GET /vlan/` → map `alias` (value sent as `group`).
+
 ## Endpoints
 
 All list endpoints return a paginated envelope and accept `?limit=&offset=` plus
@@ -173,11 +241,11 @@ curl http://10.0.1.235:8000/device/add \
  -H "Content-Type: application/json" \
  -d '{"mac_address":"14-99-3E-74-CB-7F","group":"staff","name":"Ali Hassan","phone":"7712345","alias":"Living Room TV"}' -s | jq
 
-# Edit a device (any one field: groupname and/or status)
+# Edit a device (any subset of group/status/name/phone/alias)
 curl http://10.0.1.235:8000/device/edit \
  -H "X-API-Key: staging-dev-key-change-me-7f3a9c1e5b" \
  -H "Content-Type: application/json" \
- -d '{"mac_address":"14-99-3E-74-CB-7F","status":"unpaid"}' -s | jq
+ -d '{"mac_address":"14-99-3E-74-CB-7F","status":"unpaid","alias":"Living Room TV"}' -s | jq
 
 # Delete a device
 curl http://10.0.1.235:8000/device/14-99-3E-74-CB-7F \
@@ -212,8 +280,9 @@ curl http://10.0.1.235:8000/health -s | jq
 | 200  | OK                                          |
 | 201  | Created                                     |
 | 204  | Deleted (no content)                        |
+| 400  | Bad request (e.g. referenced group/VLAN doesn't exist) |
 | 401  | Missing/invalid `X-API-Key`                 |
-| 404  | Row not found                               |
+| 404  | Row / device / VLAN not found               |
 | 409  | Duplicate / integrity conflict              |
 | 422  | Request body failed validation              |