api: support list indexes in path

1 files changed, 19 insertions, 15 deletions

diff --git a/docs/openapi.yaml b/docs/openapi.yaml
index 09d0bc6..66ff2d3 100644
--- a/docs/openapi.yaml
+++ b/docs/openapi.yaml
@@ -96,8 +96,9 @@ paths:
       tags: [Store]
       summary: Write a value
       description: |
-        Writes the value, creating intermediate maps. One request is one Automerge
-        change. Answers with the value written (JSON, or text with
+        Writes the value, creating intermediate maps (not lists). In a list, an index
+        replaces the item there, the list's length appends, and past it is `404`. One
+        request is one Automerge change. Answers with the value written (JSON, or text with
         `Accept: text/plain`).
 
         JSON maps and arrays become Automerge maps and lists; numbers become integers
@@ -133,17 +134,10 @@ paths:
       tags: [Store]
       summary: Insert into a list
       description: |
-        Inserts the value (as `PUT` takes it) into the list at the path: at `index`,
-        the items from there on moving up one, or at the end without one (or with
-        `-1`). One request is one Automerge change. To add a key to a map, `PUT` it.
-      parameters:
-        - name: index
-          in: query
-          required: false
-          description: Where, from 0 to the list's length (that's the end); `-1` is the end too.
-          schema:
-            type: integer
-            minimum: -1
+        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 replace an item, `PUT` its index.
       requestBody:
         required: true
         content:
@@ -171,6 +165,8 @@ paths:
           description: As for `PUT`.
         '404':
           description: Nothing at this path.
+        '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).
         '415':
@@ -180,10 +176,13 @@ paths:
     delete:
       tags: [Store]
       summary: Delete a value
+      description: |
+        Deletes the value; in a list, the item at the index (the items after it move
+        down one).
       parameters:
         - name: prune
           in: query
-          description: Also remove ancestor maps left empty.
+          description: Also remove ancestor maps left empty (not through a list).
           schema:
             type: boolean
             default: false
@@ -1036,7 +1035,12 @@ components:
       in: path
       required: true
       description: |
-        Slash-separated store path, e.g. `settings/theme`. A key with `/` in it, or an
+        Slash-separated store path, e.g. `settings/theme`. Within a list a segment is
+        an index (`servers/0/name`): decimal, from 0, without a sign or leading zeros;
+        anything else names nothing there (`404`). A negative index counts from the end
+        (`-1` the last item; for `POST`, the end): answered with a `307` to the path
+        with it made positive. In a map every segment is a key, `0` and `-1` too. A key
+        with `/` in it, or an
         empty key, can't be named here (neither `%2F` nor `//` helps: the path is
         split after decoding, and empty segments are `400`); such keys exist only
         inside a value written at a parent path, and are read through that parent.