summaryrefslogtreecommitdiffstats
path: root/docs/api.md
diff options
context:
space:
mode:
Diffstat (limited to 'docs/api.md')
-rw-r--r--docs/api.md31
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