aboutsummaryrefslogtreecommitdiffstats
path: root/docs/openapi.yaml
diff options
context:
space:
mode:
Diffstat (limited to 'docs/openapi.yaml')
-rw-r--r--docs/openapi.yaml230
1 files changed, 230 insertions, 0 deletions
diff --git a/docs/openapi.yaml b/docs/openapi.yaml
index 0f1af33..0bce165 100644
--- a/docs/openapi.yaml
+++ b/docs/openapi.yaml
@@ -51,6 +51,12 @@ tags:
refused (`409`).
- name: Debug
description: Test hooks, only with `--debug-api`.
+ - name: Events
+ description: |
+ A swarm holding a store (docs/store.md): its events, which whoever this node lets
+ in may have it put, whoever signed them; what its fold reads from them; and this
+ node's own refusals and drops. Only with the `federation` cargo feature; `404`
+ while the node holds no store (its swarm holds none, or it hasn't read it yet).
paths:
/store:
@@ -1405,6 +1411,221 @@ paths:
text/event-stream:
schema:
type: string
+ /events:
+ get:
+ tags: [Events]
+ summary: The store
+ description: |
+ The store's ID (its root's), its checkpoint's ID, its heads (what a new event
+ builds on) and how many events it took after its checkpoint, as this node reads
+ it now.
+ responses:
+ '200':
+ description: The store.
+ content:
+ application/json:
+ schema:
+ type: object
+ required: [store, checkpoint, heads, taken]
+ properties:
+ store:
+ type: string
+ checkpoint:
+ type: string
+ heads:
+ type: array
+ items:
+ type: string
+ taken:
+ type: integer
+ '404':
+ $ref: '#/components/responses/Error'
+ post:
+ tags: [Events]
+ summary: Put an event
+ description: |
+ Puts an event, the body as its bytes, whoever signed it: offered to the store,
+ and written into the document at its ID (the SHA-256 of its bytes) unless the
+ store refuses it. `event` says what became of it: `taken`, `held` (taken
+ before), or `waiting` for what it builds on.
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ type: object
+ responses:
+ '200':
+ description: Put.
+ content:
+ application/json:
+ schema:
+ type: object
+ required: [id, event]
+ properties:
+ id:
+ type: string
+ event:
+ type: string
+ enum: [taken, held, waiting]
+ '404':
+ $ref: '#/components/responses/Error'
+ '422':
+ description: The store refuses it; `id` and `why` say which, and why.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/Error'
+ /events/{id}:
+ get:
+ tags: [Events]
+ summary: An event
+ description: |
+ An event the store holds, taken or kept by its checkpoint, or its checkpoint, as
+ its bytes.
+ parameters:
+ - name: id
+ in: path
+ required: true
+ schema:
+ type: string
+ responses:
+ '200':
+ description: Its bytes.
+ content:
+ application/json:
+ schema:
+ type: object
+ '400':
+ $ref: '#/components/responses/Error'
+ '404':
+ $ref: '#/components/responses/Error'
+ /events/counts:
+ get:
+ tags: [Events]
+ summary: What counts
+ description: |
+ What counts, as the store reads now (docs/federation.md): the current version
+ (its number, its hash, and the version itself), each party's keys and nodes, the
+ value at each place, and the members, each `[node, party]`.
+ responses:
+ '200':
+ description: What counts.
+ content:
+ application/json:
+ schema:
+ type: object
+ required: [version, parties, values, members]
+ properties:
+ version:
+ type: object
+ parties:
+ type: object
+ values:
+ type: object
+ members:
+ type: array
+ items:
+ type: array
+ items:
+ type: string
+ '404':
+ $ref: '#/components/responses/Error'
+ /events/refused:
+ get:
+ tags: [Events]
+ summary: What the store refused
+ description: |
+ The events the store refused: `own`, those its history takes but this node
+ doesn't, by what it took before (a version changing another than the one it
+ reads), apart from the rest; `dropped`, those its operator had it drop; and
+ `refused`, every other, with why.
+ responses:
+ '200':
+ description: What it refused.
+ content:
+ application/json:
+ schema:
+ type: object
+ required: [own, dropped, refused]
+ properties:
+ own:
+ type: array
+ items:
+ type: string
+ dropped:
+ type: array
+ items:
+ type: string
+ refused:
+ type: array
+ items:
+ type: object
+ required: [id, why]
+ properties:
+ id:
+ type: string
+ why:
+ type: string
+ '404':
+ $ref: '#/components/responses/Error'
+ /admin/events/drop:
+ post:
+ tags: [Events]
+ summary: Drop events this node took
+ description: |
+ Drops events the store took after its checkpoint, with everything built on
+ them: this node refuses them from then on, from whoever brings them, and keeps
+ so across restarts (`--store-file`), until it is told otherwise
+ (`/admin/events/allow`). Not what the checkpoint keeps or holds by ID. Answers
+ what it dropped, in the order taken. Needs `write` on `_continuum`.
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/EventIds'
+ responses:
+ '200':
+ description: Dropped.
+ content:
+ application/json:
+ schema:
+ type: object
+ required: [dropped]
+ properties:
+ dropped:
+ type: array
+ items:
+ type: string
+ '400':
+ $ref: '#/components/responses/Error'
+ '404':
+ $ref: '#/components/responses/Error'
+ '422':
+ $ref: '#/components/responses/Error'
+ /admin/events/allow:
+ post:
+ tags: [Events]
+ summary: Take back what this node refused of its own, or dropped
+ description: |
+ Takes back what this node refused of its own, or dropped, among the events
+ named, and what was refused for building on them: they are taken again where the
+ store takes them, as it reads its document again. Needs `write` on
+ `_continuum`.
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/EventIds'
+ responses:
+ '204':
+ description: Taken back.
+ '400':
+ $ref: '#/components/responses/Error'
+ '404':
+ $ref: '#/components/responses/Error'
/admin/remakes:
get:
tags: [Remakes]
@@ -2078,6 +2299,15 @@ components:
$ref: '#/components/schemas/Error'
schemas:
+ EventIds:
+ type: object
+ required: [ids]
+ properties:
+ ids:
+ type: array
+ items:
+ type: string
+ description: Events by their IDs, in hex.
Limit:
type: object
properties: