diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/openapi.yaml | 230 |
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: |
