api: Document the item query parameter in the OpenAPI specs

The fallback added in this branch is a public API surface - `pi-hole/web#3818` uses `PUT /api/groups?item=...` as its regular edit path - but nothing described it.

1. `common.yaml` gains a shared `item` query parameter explaining why it exists (browsers collapse a `.`/`..` path segment) and that it is only consulted when the URI path carries no item.
2. `groups`, `clients`, `lists` and `domains` reference it on the operations that take an item, so it shows up on `GET`, `PUT` and `DELETE` alike.
3. Each of the four specs gains an `item_mismatch` example for the `400` returned when the path and the query name different items.

We deliberately do not add `put`/`delete` to the item-less path objects (e.g., `/groups`): FTL reports its endpoints from a static table that lists those methods under `/groups/{name}`, and `test_all_endpoints_cross_check` compares the specs against that table in both directions.

Signed-off-by: DL6ER <dl6er@dl6er.de>

Author: DL6ER

src/api/docs/content/specs/clients.yaml

@@ -5,6 +5,7 @@ components:
       summary: Modify client
       parameters:
         - $ref: 'clients.yaml#/components/parameters/client'
+        - $ref: 'common.yaml#/components/parameters/item'
       get:
         summary: Get clients
         tags:
@@ -75,6 +76,8 @@ components:
                 examples:
                   item_missing:
                     $ref: 'clients.yaml#/components/examples/errors/uri_error/item_missing'
+                  item_mismatch:
+                    $ref: 'clients.yaml#/components/examples/errors/bad_request/item_mismatch'
                   no_payload:
                     $ref: 'clients.yaml#/components/examples/errors/bad_request/no_payload'
                   duplicate:
@@ -114,6 +117,8 @@ components:
                 examples:
                   item_missing:
                     $ref: 'clients.yaml#/components/examples/errors/uri_error/item_missing'
+                  item_mismatch:
+                    $ref: 'clients.yaml#/components/examples/errors/bad_request/item_mismatch'
           '401':
             description: Unauthorized
             content:
@@ -507,6 +512,14 @@ components:
               message: "Invalid request body data (no valid JSON)"
               hint: null
             took: 0.003
+        item_mismatch:
+          summary: URI path and "item" query parameter name different clients
+          value:
+            error:
+              key: "bad_request"
+              message: 'Invalid request: The item in the URI path and the "item" query parameter disagree'
+              hint: "/api/clients/192.168.2.5"
+            took: 0.003
       database_error:
         duplicate:
           summary: Database error

src/api/docs/content/specs/common.yaml

@@ -104,3 +104,16 @@ components:
           type: boolean
         required: false
         example: false
+    item:
+      in: query
+      name: item
+      description: |
+        The item to operate on, as an alternative to naming it in the URI path.
+
+        Browsers remove a path segment that is `.` or `..` - as well as their percent-encoded forms `%2e` and `%2e%2e` - while they resolve a URL, so an item with such a name can never reach Pi-hole as part of the path. A query parameter is not subject to this normalization, e.g., `PUT /api/groups?item=.`
+
+        The value is used whenever the URI path carries no item. Both may be given at the same time as long as they are identical: the path is what identifies the resource, so a disagreement is rejected with `400` instead of being silently resolved in favor of either one.
+      schema:
+        type: string
+      required: false
+      example: "."

src/api/docs/content/specs/domains.yaml

@@ -54,6 +54,7 @@ components:
         - $ref: 'domains.yaml#/components/parameters/type'
         - $ref: 'domains.yaml#/components/parameters/kind'
         - $ref: 'domains.yaml#/components/parameters/domain'
+        - $ref: 'common.yaml#/components/parameters/item'
       get:
         operationId: "get_domain"
         <<: *get_path
@@ -107,6 +108,8 @@ components:
                     $ref: 'domains.yaml#/components/examples/errors/uri_error/list_imprecise'
                   item_missing:
                     $ref: 'domains.yaml#/components/examples/errors/uri_error/item_missing'
+                  item_mismatch:
+                    $ref: 'domains.yaml#/components/examples/errors/bad_request/item_mismatch'
                   no_payload:
                     $ref: 'domains.yaml#/components/examples/errors/bad_request/no_payload'
                   duplicate:
@@ -150,6 +153,8 @@ components:
                     $ref: 'domains.yaml#/components/examples/errors/uri_error/list_imprecise'
                   item_missing:
                     $ref: 'domains.yaml#/components/examples/errors/uri_error/item_missing'
+                  item_mismatch:
+                    $ref: 'domains.yaml#/components/examples/errors/bad_request/item_mismatch'
           '401':
             description: Unauthorized
             content:
@@ -519,6 +524,14 @@ components:
               message: "Invalid request body data (no valid JSON)"
               hint: null
             took: 0.003
+        item_mismatch:
+          summary: URI path and "item" query parameter name different domains
+          value:
+            error:
+              key: "bad_request"
+              message: 'Invalid request: The item in the URI path and the "item" query parameter disagree'
+              hint: "/api/domains/deny/exact/example.com"
+            took: 0.003
       database_error:
         duplicate:
           summary: Database error

src/api/docs/content/specs/groups.yaml

@@ -5,6 +5,7 @@ components:
       summary: Modify group
       parameters:
         - $ref: 'groups.yaml#/components/parameters/name'
+        - $ref: 'common.yaml#/components/parameters/item'
       get:
         summary: Get groups
         tags:
@@ -77,6 +78,8 @@ components:
                 examples:
                   item_missing:
                     $ref: 'groups.yaml#/components/examples/errors/uri_error/item_missing'
+                  item_mismatch:
+                    $ref: 'groups.yaml#/components/examples/errors/bad_request/item_mismatch'
                   no_payload:
                     $ref: 'groups.yaml#/components/examples/errors/bad_request/no_payload'
                   duplicate:
@@ -116,6 +119,8 @@ components:
                 examples:
                   item_missing:
                     $ref: 'groups.yaml#/components/examples/errors/uri_error/item_missing'
+                  item_mismatch:
+                    $ref: 'groups.yaml#/components/examples/errors/bad_request/item_mismatch'
           '401':
             description: Unauthorized
             content:
@@ -421,6 +426,14 @@ components:
               message: "Invalid request body data (no valid JSON)"
               hint: null
             took: 0.003
+        item_mismatch:
+          summary: URI path and "item" query parameter name different groups
+          value:
+            error:
+              key: "bad_request"
+              message: 'Invalid request: The item in the URI path and the "item" query parameter disagree'
+              hint: "/api/groups/my_group"
+            took: 0.003
       database_error:
         duplicate:
           summary: Database error

src/api/docs/content/specs/lists.yaml

@@ -8,6 +8,7 @@ components:
         parameters:
           - $ref: 'lists.yaml#/components/parameters/list'
           - $ref: 'lists.yaml#/components/parameters/listtype_optional'
+          - $ref: 'common.yaml#/components/parameters/item'
         tags:
           - "List management"
         operationId: "get_lists"
@@ -42,6 +43,7 @@ components:
         parameters:
           - $ref: 'lists.yaml#/components/parameters/list'
           - $ref: 'lists.yaml#/components/parameters/listtype'
+          - $ref: 'common.yaml#/components/parameters/item'
         tags:
           - "List management"
         operationId: "replace_lists"
@@ -77,6 +79,8 @@ components:
                 examples:
                   item_missing:
                     $ref: 'lists.yaml#/components/examples/errors/uri_error/item_missing'
+                  item_mismatch:
+                    $ref: 'lists.yaml#/components/examples/errors/bad_request/item_mismatch'
                   no_payload:
                     $ref: 'lists.yaml#/components/examples/errors/bad_request/no_payload'
                   duplicate:
@@ -94,6 +98,7 @@ components:
         parameters:
           - $ref: 'lists.yaml#/components/parameters/list'
           - $ref: 'lists.yaml#/components/parameters/listtype'
+          - $ref: 'common.yaml#/components/parameters/item'
         tags:
           - "List management"
         operationId: "delete_lists"
@@ -120,6 +125,8 @@ components:
                 examples:
                   item_missing:
                     $ref: 'lists.yaml#/components/examples/errors/uri_error/item_missing'
+                  item_mismatch:
+                    $ref: 'lists.yaml#/components/examples/errors/bad_request/item_mismatch'
           '401':
             description: Unauthorized
             content:
@@ -491,6 +498,14 @@ components:
               message: "Invalid request body data (no valid JSON)"
               hint: null
             took: 0.003
+        item_mismatch:
+          summary: URI path and "item" query parameter name different lists
+          value:
+            error:
+              key: "bad_request"
+              message: 'Invalid request: The item in the URI path and the "item" query parameter disagree'
+              hint: "/api/lists/https://example.com/list.txt"
+            took: 0.003
       database_error:
         duplicate:
           summary: Database error