api: add support for counters

1 files changed, 22 insertions, 3 deletions

diff --git a/docs/openapi.yaml b/docs/openapi.yaml
index cc898e6..fac802d 100644
--- a/docs/openapi.yaml
+++ b/docs/openapi.yaml
@@ -139,14 +139,27 @@ paths:
           description: 'Node is not ready (and isn''t rejoining: a rejoining node takes writes into its document before the rejoin, carried over when it ends).'
     post:
       tags: [Store]
-      summary: Insert into a list
+      summary: Insert into a list, or increment a counter
       description: |
         Inserts the value (as `PUT` takes it) into a list: the path ends in the index
         it goes to (`queue/2`), the items from there on moving up one; the list's
         length, or `-1` (a `307` to it), appends. One request is one Automerge change.
         To add a key to a map, `PUT` it; to overwrite an item, `PUT` its index.
+
+        With `increment`, adds it to the counter at the path instead (no body): one
+        is made where there is nothing (in a map; a list's items are only
+        incremented, `-1` naming the last). Increments of a counter on several nodes
+        add up. Answers `200` with the counter's value then. Reads show a counter as
+        a number; a `PUT` there makes it a plain number again.
+      parameters:
+        - name: increment
+          in: query
+          description: How much to add (negative to subtract).
+          schema:
+            type: integer
+            format: int64
       requestBody:
-        required: true
+        required: false
         content:
           application/json:
             schema: {}
@@ -154,6 +167,12 @@ paths:
             schema:
               type: string
       responses:
+        '200':
+          description: With `increment`, the counter's value after it.
+          content:
+            application/json:
+              schema:
+                type: integer
         '201':
           description: Inserted, and where.
           content:
@@ -175,7 +194,7 @@ paths:
         '307':
           description: A negative index, made positive (`Location`).
         '409':
-          description: Not a list there, or the index is past its end (the message says which, and the length).
+          description: Not a list there, or the index is past its end (the message says which, and the length); with `increment`, not a counter there.
         '415':
           description: Content-Type is neither `application/json` nor `text/plain` (absent means JSON).
         '503':