docs: add collections API endpoint files (Phase 2 completion)

2026-02-02 15:54:59 -05:00
parent a3a3d4ed40
commit ec74650c18
11 changed files with 636 additions and 0 deletions
@@ -0,0 +1,71 @@
+# Test Rule
+
+Test which books would match given rules without saving.
+
+**Endpoint**: `POST /api/collections/test-rules`
+**Auth**: Required
+**Content-Type**: `application/json`
+
+## Request Body
+
+| Field | Type | Required | Description |
+|--------|------|-----------|-------------|
+| rules | array | Yes | Array of rule objects to test |
+
+### Rule Object
+
+| Field | Type | Required | Description |
+|--------|------|-----------|-------------|
+| field | string | Yes | Field to match on (genre, author, series, language, publisher, copyright_year, tags) |
+| operator | string | Yes | Comparison operator (equals, not_equals, contains, not_contains, starts_with, ends_with, greater_than, less_than) |
+| value | string/number | Yes | Value to compare against |
+
+### Example Request
+
+```json
+{
+  "rules": [
+    {
+      "field": "genre",
+      "operator": "equals",
+      "value": "Science Fiction"
+    },
+    {
+      "field": "author",
+      "operator": "contains",
+      "value": "Asimov"
+    }
+  ]
+}
+```
+
+## Response (200 OK)
+
+```json
+{
+  "matches": [
+    {
+      "media_item_id": "660e8400-e29b-41d4-a716-446655440000",
+      "title": "Foundation",
+      "author": "Isaac Asimov",
+      "cover_image_path": "/covers/foundation.jpg",
+      "match_reason": "Matched rule: genre equals Science Fiction"
+    }
+  ],
+  "total": 42
+}
+```
+
+## Use Case
+
+Test rules before creating a collection to verify correct book matching. This endpoint shows which books would be added without actually modifying any collections.
+
+## Error Responses
+
+| Code | Description |
+|------|-------------|
+| 400 | Invalid request (validation failed) |
+| 401 | Authentication required |
+| 500 | Internal server error |
+
+## Try It Out