From ee8bd5ad52a0e61466cef2a7a1ac4779ab2aa3af Mon Sep 17 00:00:00 2001 From: Shihaam Abdul Rahman Date: Fri, 31 Jul 2026 21:28:34 +0500 Subject: [PATCH] update docs --- README.md | 75 ++++++++++++++++++++++++++++++++++++++++++++++++--- docs.txt.save | 71 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 143 insertions(+), 3 deletions(-) create mode 100644 docs.txt.save diff --git a/README.md b/README.md index 6e48ee5..c0703b8 100644 --- a/README.md +++ b/README.md @@ -55,6 +55,74 @@ X-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: ` (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 | diff --git a/docs.txt.save b/docs.txt.save new file mode 100644 index 0000000..de2c833 --- /dev/null +++ b/docs.txt.save @@ -0,0 +1,71 @@ + +adding a new device +example post /device/new +macaddress,group +removing an existing device + +listing vlans +GET /vlan/ +SELECT * FROM `radgroupreply` +this will return 3 duplicate "groupnames" with different attribute and vlaue +only need to return group name and value for Tunnel-Private-Group-Id + +adding new vlan +need to add 3 items with different attribute and value, +for example to add staff vlan with vlan ID 55 +api call should be like POST vlan/add and json data vlanid:55, alias staff + +'INSERT INTO `radgroupreply` (`groupname`, `attribute`, `op`, `value`) +VALUES ('staff', 'Tunnel-Type', '=', 'VLAN'); + +INSERT INTO `radgroupreply` (`groupname`, `attribute`, `op`, `value`) +VALUES ('staff', 'Tunnel-Medium-Type', '=', 'IEEE-802'); + +INSERT INTO `radgroupreply` (`groupname`, `attribute`, `op`, `value`) +VALUES ('staff', 'Tunnel-Private-Group-Id', '=', '55'); +' +deleting existing vlan +you get api call to delete vlan +DELETE vlan/55 +and the sqlcommands should you looking for Tunnel-Private-Group-Id=55 and then deleting all the maching group names + +edit existing vlan (alias) +post request, and allow to edit alias + +disallow to add duplicate vlans or alias + +listing existing devices +get /device/ +SELECT * FROM `radusergroup` +and then +SELECT * FROM `customers` +return mac address, groupname and status + +adding new device +this input feils are +' +POST /device/add with mac address and group and it involves few Commands +` +SELECT * FROM `radgroupreply` +# and see if the group in the device add command exists +# respond 4xx (whatever needed with reason group not found) +# else continue + +INSERT INTO `radcheck` (`username`, `attribute`, `op`, `value`) +VALUES ('14-99-3E-74-CB-7F', 'Cleartext-Password', ':=', '14-99-3E-74-CB-7F'); + +INSERT INTO `radusergroup` (`username`, `groupname`, `priority`) +VALUES ('14-99-3E-74-CB-7F', 'staff', '1'); + +INSERT INTO `customers` (`username`, `mac_address`, `status`, `created_at`) +VALUES ('14-99-3E-74-CB-7F', '14-99-3E-74-CB-7F', 'paid', now()); +` + +deleting existing deivce +edit existing device (input macaddress, edit groupname, edit status. do allow to edit just 1 feild) +use sesnible commands based on add devices + +i would also like a device alias, added to customers table like +"Customer name, device name, phone number" +these are to be ignored by radius server, but helpful for human review +and add input fields during adding device and also listing devices