diff options
Diffstat (limited to 'docs/api.md')
| -rw-r--r-- | docs/api.md | 31 |
1 files changed, 17 insertions, 14 deletions
diff --git a/docs/api.md b/docs/api.md index 05abf44..418d7b9 100644 --- a/docs/api.md +++ b/docs/api.md @@ -26,12 +26,14 @@ curl -u alice:secret -X POST 'localhost:3000/store/stats/visits?increment=1' # * `GET /store/<path>` reads, `PUT` writes (what is there then reads as the value written; the maps on the way are created), `DELETE` deletes (`?prune=true` also removes the maps it leaves empty), and `POST` inserts into a list at an index, the - items from there moving up, or with `?increment=n` adds `n` to a counter (Concurrent - writes), or with `?cast=<type>` casts what is there to another type (Types). - `?signed=true` on any of them has the node sign the change (Signed changes). + items from there moving up, or with `?increment=n` adds `n` to a counter + ([Concurrent writes](#concurrent-writes)), or with `?cast=<type>` casts what is there to + another type ([Types](#types)). `?signed=true` on any of them has the node sign the + change ([Signed changes](#signed-changes)). * Bodies are JSON (`application/json`, the default), text (`text/plain`, stored as a - string), or a value of a type of its own (Types); answers are JSON, or as `Accept` - asks. Numbers in JSON are stored as integers where they fit, as floats otherwise. + string), or a value of a type of its own ([Types](#types)); answers are JSON, or as + `Accept` asks. Numbers in JSON are stored as integers where they fit, as floats + otherwise. * Every request needs a user from the node's `--htpasswd` (basic authentication: send the password with the request, as `curl -u` does; the node asks for one with a `401`'s `WWW-Authenticate` only of what isn't a browser, by its `Sec-Fetch-*` @@ -165,9 +167,9 @@ way on every node: Automerge's operation order (the write made after seeing more changes; between equals, by the writer's actor ID), not by any clock: of two truly concurrent writes, which wins is arbitrary, but it is the same on every node. Where the swarm's policy asks for - signed values (Signed values, below), a string that is an envelope comes before - anything else written there at once, a map too: of those, the one its user numbered - highest (`seq`), of equal ones the one with the lower SHA-256. + signed values ([Signed values](#signed-values), below), a string that is an envelope + comes before anything else written there at once, a map too: of those, the one its user + numbered highest (`seq`), of equal ones the one with the lower SHA-256. * **Maps written at the same key** merge into one: their keys are united, each key as above. * **A write and a delete** of the same key: the write stays (a delete removes only what @@ -225,8 +227,8 @@ A node serves the store once it holds the swarm's document ([`lifecycle.md`](lif * **Rejoining** a newer epoch after a remake it missed: reads answer from the document before, with `x-continuum-stale` naming that epoch; writes are answered as usual and go into that document (so reads show them), carried over into the new epoch when the - rejoin ends, unless newer writes touched their paths (Concurrent writes); streams are - `503`. + rejoin ends, unless newer writes touched their paths + ([Concurrent writes](#concurrent-writes)); streams are `503`. * **Remakes** ([`remakes.md`](remakes.md)) don't interrupt anything else: a node switches to the new document between two requests, and writes made meanwhile are carried over (at their path, or where the remake's rules put them; [`remakes.md`](remakes.md), Writes around a @@ -245,10 +247,11 @@ are each node's own (`--htpasswd`, or its proxy's): `alice` on two nodes is one only where their operators make it so, which nothing checks. `GET /admin/changes` lists them, newest first, with the paths each touched and whether a signature by its node vouches -for it (`verified`, Signed changes), and `GET /admin/refused` those this node refused under the swarm's policy ([`access.md`](access.md), Changes judged on every node); `GET /admin/changes/settings` those that -touched what is at `settings`. -Every node holds every change, so user names are known to the whole swarm, and so is -who wrote what, until a remake drops the history ([`remakes.md`](remakes.md)). +for it (`verified`, [Signed changes](#signed-changes)), and `GET /admin/refused` those +this node refused under the swarm's policy ([`access.md`](access.md), Changes judged on +every node); `GET /admin/changes/settings` those that touched what is at `settings`. Every +node holds every change, so user names are known to the whole swarm, and so is who wrote +what, until a remake drops the history ([`remakes.md`](remakes.md)). ## Signed changes |
