api: add type casts

1 files changed, 25 insertions, 4 deletions

diff --git a/docs/openapi.yaml b/docs/openapi.yaml
index 6e106b9..f188d69 100644
--- a/docs/openapi.yaml
+++ b/docs/openapi.yaml
@@ -177,7 +177,7 @@ 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, or increment a counter
+      summary: Insert into a list, increment a counter, or cast a value
       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
@@ -189,6 +189,14 @@ paths:
         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.
+
+        With `cast`, casts what is at the path to that type instead (no body; `-1`
+        names the last item): numbers (integers, floats, counters, timestamps as
+        milliseconds since 1970) to numbers where they are exactly that, any scalar
+        but bytes to a string or a text as its media type shows it (timestamps in
+        `format`) and back, bytes to a string or a text and back as UTF-8. Answers
+        `200` with what is there then, as `PUT` does (`x-continuum-retyped` saying
+        the change).
       parameters:
         - name: increment
           in: query
@@ -196,6 +204,19 @@ paths:
           schema:
             type: integer
             format: int64
+        - name: cast
+          in: query
+          description: The type to cast to.
+          schema:
+            type: string
+            enum: [text, string, bytes, int, uint, float, boolean, counter, timestamp]
+        - name: format
+          in: query
+          description: With `cast`, how timestamps are read from and written as strings.
+          schema:
+            type: string
+            enum: [rfc3339, unix, unix-ms, http-date]
+            default: rfc3339
       requestBody:
         required: false
         content:
@@ -206,7 +227,7 @@ paths:
               type: string
       responses:
         '200':
-          description: With `increment`, the counter's value after it.
+          description: With `increment`, the counter's value after it; with `cast`, what is there after it (as `GET` shows it, with `x-continuum-type` and `x-continuum-retyped`).
           headers:
             x-continuum-heads:
               $ref: '#/components/headers/WrittenHeads'
@@ -228,7 +249,7 @@ paths:
                   index:
                     type: integer
         '400':
-          description: Invalid path, index, malformed JSON or invalid UTF-8.
+          description: Invalid path, index, malformed JSON or invalid UTF-8; an unknown `cast` type or `format`, or both `increment` and `cast`.
         '401':
           $ref: '#/components/responses/Unauthorized'
         '403':
@@ -238,7 +259,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); with `increment`, not a counter there.
+          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; with `cast`, no cast possible (the message says why).
         '415':
           description: Content-Type is none the API takes (`application/json`, the default; `text/plain`; a type's own, `api.md`, Types).
         '503':