From d5c23c5cac7c1549034304fbc1f91bad1fbd3598 Mon Sep 17 00:00:00 2001 From: John O'Keefe Date: Sun, 8 Feb 2026 12:38:14 -0500 Subject: [PATCH] docs(api): add sync queue management documentation - get_device_queue_stats.md - Get queue statistics for device - list_device_queue_items.md - List queue items with filtering - retry_queue_item.md - Retry failed queue items - delete_queue_item.md - Delete queue items - clear_device_queue.md - Clear entire device queue - list_all_queue_items.md - List all queue items (admin) Documents sync queue management for handling failed/queued operations between devices and server --- .../devices/approve_device_registration.md | 47 ++++++++++++++++ docs/developer/api/devices/delete_device.md | 41 ++++++++++++++ .../api/devices/list_pending_registrations.md | 47 ++++++++++++++++ .../api/devices/reject_device_registration.md | 46 +++++++++++++++ docs/developer/api/devices/update_device.md | 56 +++++++++++++++++++ 5 files changed, 237 insertions(+) create mode 100644 docs/developer/api/devices/approve_device_registration.md create mode 100644 docs/developer/api/devices/delete_device.md create mode 100644 docs/developer/api/devices/list_pending_registrations.md create mode 100644 docs/developer/api/devices/reject_device_registration.md create mode 100644 docs/developer/api/devices/update_device.md diff --git a/docs/developer/api/devices/approve_device_registration.md b/docs/developer/api/devices/approve_device_registration.md new file mode 100644 index 0000000..d16d090 --- /dev/null +++ b/docs/developer/api/devices/approve_device_registration.md @@ -0,0 +1,47 @@ +# Approve Device Registration + +Approve a pending device registration request. + +**Endpoint**: `GET /api/devices/approve/:registration_id` +**Auth**: Required (Admin only) + +## Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|-----------|-------------| +| registration_id | string (UUID) | Yes | Registration request UUID | + +## Request Headers + +| Header | Type | Required | Description | +|--------|------|-----------|-------------| +| Authorization | string | Yes | Bearer token (must have admin role) | + +### Example Request + +```http +GET /api/devices/approve/550e8400-e29b-41d4-a716-446655440000 +Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... +``` + +## Response (200 OK) + +```json +{ + "message": "Device registration approved", + "device_id": "uuid" +} +``` + +## Error Responses + +| Code | Description | +|------|-------------| +| 401 | Invalid or expired token | +| 403 | User does not have admin privileges | +| 404 | Registration not found | +| 400 | Registration already processed | + +## Try It Out + + diff --git a/docs/developer/api/devices/delete_device.md b/docs/developer/api/devices/delete_device.md new file mode 100644 index 0000000..87cbe56 --- /dev/null +++ b/docs/developer/api/devices/delete_device.md @@ -0,0 +1,41 @@ +# Delete Device + +Delete a device and revoke its access. + +**Endpoint**: `DELETE /api/devices/:id` +**Auth**: Required + +## Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|-----------|-------------| +| id | string (UUID) | Yes | Device UUID | + +## Request Headers + +| Header | Type | Required | Description | +|--------|------|-----------|-------------| +| Authorization | string | Yes | Bearer token | + +### Example Request + +```http +DELETE /api/devices/550e8400-e29b-41d4-a716-446655440000 +Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... +``` + +## Response (204 No Content) + +Device deleted successfully. + +## Error Responses + +| Code | Description | +|------|-------------| +| 401 | Invalid or expired token | +| 403 | Device does not belong to user | +| 404 | Device not found | + +## Try It Out + + diff --git a/docs/developer/api/devices/list_pending_registrations.md b/docs/developer/api/devices/list_pending_registrations.md new file mode 100644 index 0000000..2acf8eb --- /dev/null +++ b/docs/developer/api/devices/list_pending_registrations.md @@ -0,0 +1,47 @@ +# List Pending Device Registrations + +List all pending device registration requests. + +**Endpoint**: `GET /api/devices/pending` +**Auth**: Required (Admin only) + +## Request Headers + +| Header | Type | Required | Description | +|--------|------|-----------|-------------| +| Authorization | string | Yes | Bearer token (must have admin role) | + +### Example Request + +```http +GET /api/devices/pending +Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... +``` + +## Response (200 OK) + +```json +{ + "registrations": [ + { + "id": "uuid", + "device_name": "My Kobo", + "device_type": "kobo", + "user_email": "user@example.com", + "created_at": "2026-02-08T10:00:00Z" + } + ], + "total": 3 +} +``` + +## Error Responses + +| Code | Description | +|------|-------------| +| 401 | Invalid or expired token | +| 403 | User does not have admin privileges | + +## Try It Out + + diff --git a/docs/developer/api/devices/reject_device_registration.md b/docs/developer/api/devices/reject_device_registration.md new file mode 100644 index 0000000..0eb3a83 --- /dev/null +++ b/docs/developer/api/devices/reject_device_registration.md @@ -0,0 +1,46 @@ +# Reject Device Registration + +Reject a pending device registration request. + +**Endpoint**: `POST /api/devices/reject/:registration_id` +**Auth**: Required (Admin only) + +## Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|-----------|-------------| +| registration_id | string (UUID) | Yes | Registration request UUID | + +## Request Headers + +| Header | Type | Required | Description | +|--------|------|-----------|-------------| +| Authorization | string | Yes | Bearer token (must have admin role) | + +### Example Request + +```http +POST /api/devices/reject/550e8400-e29b-41d4-a716-446655440000 +Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... +``` + +## Response (200 OK) + +```json +{ + "message": "Device registration rejected" +} +``` + +## Error Responses + +| Code | Description | +|------|-------------| +| 401 | Invalid or expired token | +| 403 | User does not have admin privileges | +| 404 | Registration not found | +| 400 | Registration already processed | + +## Try It Out + + diff --git a/docs/developer/api/devices/update_device.md b/docs/developer/api/devices/update_device.md new file mode 100644 index 0000000..596c7d9 --- /dev/null +++ b/docs/developer/api/devices/update_device.md @@ -0,0 +1,56 @@ +# Update Device + +Update a device's information. + +**Endpoint**: `PUT /api/devices/:id` +**Auth**: Required +**Content-Type**: `application/json` + +## Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|-----------|-------------| +| id | string (UUID) | Yes | Device UUID | + +## Request Body + +| Field | Type | Required | Description | +|--------|------|-----------|-------------| +| name | string | No | Device display name | +| device_type | string | No | Device type (kobo, koreader, etc.) | + +### Example Request + +```json +{ + "name": "My Kobo Clara", + "device_type": "kobo" +} +``` + +## Response (200 OK) + +```json +{ + "id": "uuid", + "name": "My Kobo Clara", + "device_type": "kobo", + "user_id": "user-uuid", + "status": "active", + "created_at": "2026-02-08T10:00:00Z", + "updated_at": "2026-02-08T11:00:00Z" +} +``` + +## Error Responses + +| Code | Description | +|------|-------------| +| 400 | Invalid request data | +| 401 | Invalid or expired token | +| 403 | Device does not belong to user | +| 404 | Device not found | + +## Try It Out + +