api: introduce /admin/changes

1 files changed, 107 insertions, 0 deletions

diff --git a/docs/openapi.yaml b/docs/openapi.yaml
index 662b46b..0c24110 100644
--- a/docs/openapi.yaml
+++ b/docs/openapi.yaml
@@ -458,6 +458,113 @@ paths:
         '503':
           description: Node is not ready.
 
+  /admin/changes:
+    get:
+      tags: [Admin]
+      summary: Who wrote what
+      description: |
+        The document's changes, newest first: each with when (its writer's clock, Unix
+        ms; 0 for a remake's snapshot), the node that made it (`node`, its node ID) and,
+        for a write through the API, the user it was made for (`user`), and the store
+        paths it touched (a list's items by index). Every node holds every change, so
+        any node answers for the whole swarm, as far as it has synced; history before
+        the last remake is gone with it (`remakes.md`). Changes made before nodes
+        recorded their writers have neither `node` nor `user`.
+      parameters:
+        - name: limit
+          in: query
+          description: How many at most (default 100, at most 1000).
+          schema:
+            type: integer
+            minimum: 1
+      responses:
+        '200':
+          description: The changes.
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [changes, more]
+                properties:
+                  changes:
+                    type: array
+                    items:
+                      type: object
+                      required: [hash, at, paths]
+                      properties:
+                        hash:
+                          type: string
+                        at:
+                          type: integer
+                        node:
+                          type: string
+                        user:
+                          type: string
+                        paths:
+                          type: array
+                          items:
+                            type: string
+                  more:
+                    type: boolean
+                    description: Older changes weren't looked at.
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '503':
+          description: Node is not ready.
+
+  /admin/changes/{key}:
+    get:
+      tags: [Admin]
+      summary: Who wrote what, at a path
+      description: |
+        As `/admin/changes`, but only the changes that touched what is at the path (as
+        `/store/{key}` names it), inside it or above it. At most 10000 changes are
+        looked at for it.
+      parameters:
+        - $ref: '#/components/parameters/key'
+        - name: limit
+          in: query
+          description: How many at most (default 100, at most 1000).
+          schema:
+            type: integer
+            minimum: 1
+      responses:
+        '200':
+          description: The changes.
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [changes, more]
+                properties:
+                  changes:
+                    type: array
+                    items:
+                      type: object
+                      required: [hash, at, paths]
+                      properties:
+                        hash:
+                          type: string
+                        at:
+                          type: integer
+                        node:
+                          type: string
+                        user:
+                          type: string
+                        paths:
+                          type: array
+                          items:
+                            type: string
+                  more:
+                    type: boolean
+                    description: Older changes weren't looked at.
+        '400':
+          description: A path with an empty segment.
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '503':
+          description: Node is not ready.
+
   /admin/config:
     get:
       tags: [Admin]