diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/openapi.yaml | 47 |
1 files changed, 39 insertions, 8 deletions
diff --git a/docs/openapi.yaml b/docs/openapi.yaml index 0aea4a6..5402389 100644 --- a/docs/openapi.yaml +++ b/docs/openapi.yaml @@ -77,9 +77,14 @@ paths: tags: [Store] summary: Read a value description: | - The value at the path, as JSON, or with `Accept: text/plain` as text (strings - unquoted, anything else as JSON). Concurrent writes resolve as follows: - concurrent maps merge, anything else keeps the newest write. + The value at the path, as JSON, or as `Accept` asks (`api.md`, Types): its + type's own media type for a scalar (`application/octet-stream` for bytes, + `application/vnd.continuum.<type>`), or `text/plain` (strings unquoted, + anything else as JSON). `Accept` is taken in its order; `406` if it names + nothing the value can be shown as. `application/json; timestamp-format=…` shows + timestamps as `rfc3339` (the default), `unix`, `unix-ms` or `http-date`. + Concurrent writes resolve as follows: concurrent maps merge, anything else + keeps the newest write. parameters: - $ref: '#/components/parameters/conflicts' - $ref: '#/components/parameters/heads' @@ -94,6 +99,8 @@ paths: $ref: '#/components/responses/Unauthorized' '404': description: No value at this path (with `at`, then), or this node lacks the heads `at` names. + '406': + description: '`Accept` names nothing the value can be shown as; the message says what it can.' '500': description: Reading or serializing failed. '503': @@ -105,11 +112,16 @@ paths: Writes the value, creating intermediate maps (not lists): the path then reads as the value, what was there changed only where it differs (`api.md`, Concurrent writes). In a list, an index overwrites 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`). + appends, and past it is `404`. One request is one Automerge change. Answers + with the value written, shown as `Accept` asks (as a read). JSON maps and arrays become Automerge maps and lists; numbers become integers when they fit, floats otherwise; strings are plain strings (not text objects). + A scalar of another type is written as its media type (`api.md`, Types): + `application/octet-stream` (bytes), `application/vnd.continuum.int`, `.uint`, + `.float`, `.boolean`, `.counter` (decimal or `true`/`false`), or + `application/vnd.continuum.timestamp; format=rfc3339|unix|unix-ms|http-date`; + a body that isn't one is `400`, saying why. requestBody: required: true content: @@ -120,6 +132,14 @@ paths: schema: type: string example: dark + application/octet-stream: + schema: + type: string + format: binary + application/vnd.continuum.timestamp: + schema: + type: string + example: '2026-11-01T21:50:20.345Z' responses: '200': $ref: '#/components/responses/Value' @@ -132,7 +152,7 @@ paths: '409': description: The path crosses an existing non-map value. '415': - description: Content-Type is neither `application/json` nor `text/plain` (absent means JSON). + description: Content-Type is none the API takes (`application/json`, the default; `text/plain`; a type's own, `api.md`, Types). '500': description: Writing failed. '503': @@ -202,7 +222,7 @@ paths: '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. '415': - description: Content-Type is neither `application/json` nor `text/plain` (absent means JSON). + description: Content-Type is none the API takes (`application/json`, the default; `text/plain`; a type's own, `api.md`, Types). '503': 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).' delete: @@ -1263,7 +1283,7 @@ components: description: | Instead of the value, what is there one level deep, as JSON, to browse a large store a level at a time: `type` (`map`, `list`, `text`, `string`, `bytes`, - `number`, `boolean`, `null`, `unknown`), `size` (a map's keys, a list's items, + `int`, `uint`, `float`, `boolean`, `null`, `counter`, `timestamp`, `unknown`), `size` (a map's keys, a list's items, a text's characters, a string's or bytes' bytes), `value` for a scalar up to 256 bytes, and for a map `entries`: each key's summary (without entries of its own). Concurrent values resolved as a read resolves them. Not with `conflicts` @@ -1344,6 +1364,10 @@ components: description: SHA-256 of the body. schema: type: string + x-continuum-type: + description: What the value is stored as (`map`, `list`, `text`, `string`, `bytes`, `int`, `uint`, `float`, `boolean`, `null`, `counter`, `timestamp`). + schema: + type: string content: application/json: schema: @@ -1353,6 +1377,13 @@ components: text/plain: schema: type: string + application/octet-stream: + schema: + type: string + format: binary + application/vnd.continuum.timestamp: + schema: + type: string Error: description: Error. content: |