From ce0e9b8f19d8406f617776f4057b5ba6651d1b6c Mon Sep 17 00:00:00 2001
From: Jean-Paul Calderone <exarkun@twistedmatrix.com>
Date: Thu, 20 Jan 2022 21:23:33 -0500
Subject: [PATCH] sketch the api a bit
---
docs/requirements.txt | 1 +
docs/source/conf.py | 1 +
docs/source/designs/backup-recovery.rst | 2 +-
docs/source/designs/backup-recovery.yaml | 72 ++++++++++++++++++++++++
shell.nix | 2 +
5 files changed, 77 insertions(+), 1 deletion(-)
create mode 100644 docs/source/designs/backup-recovery.yaml
diff --git a/docs/requirements.txt b/docs/requirements.txt
index 6966869..cd7c306 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1 +1,2 @@
sphinx
+sphinxcontrib-openapi
diff --git a/docs/source/conf.py b/docs/source/conf.py
index dacdfe5..f5dd3d4 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -39,6 +39,7 @@ release = '0.0'
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
+ "sphinxcontrib.openapi",
]
# Add any paths that contain templates here, relative to this directory.
diff --git a/docs/source/designs/backup-recovery.rst b/docs/source/designs/backup-recovery.rst
index 15bef98..7c9c07d 100644
--- a/docs/source/designs/backup-recovery.rst
+++ b/docs/source/designs/backup-recovery.rst
@@ -205,7 +205,7 @@ Backup operations resume as usual from this point using the existing on-grid sta
External Interfaces
~~~~~~~~~~~~~~~~~~~
-
+.. openapi:: ./backup-recovery.yaml
Data Integrity
~~~~~~~~~~~~~~
diff --git a/docs/source/designs/backup-recovery.yaml b/docs/source/designs/backup-recovery.yaml
new file mode 100644
index 0000000..fd73f61
--- /dev/null
+++ b/docs/source/designs/backup-recovery.yaml
@@ -0,0 +1,72 @@
+openapi: "3.1.0"
+info:
+ title: "Backup / Recovery"
+ description: |
+ This API allows backup and recovery of ZKAPAuthorizer internal state.
+ version: "1.0.0"
+paths:
+ /storage-plugins/privatestorageio-zkapauthz-v1/recover:
+ post:
+ description: |
+ Recover ZKAPAuthorizer state from a previously configured backup.
+ This is only valid when ZKAPAuthorizer has no local state yet.
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ recovery-capability:
+ type: "string"
+ description: |
+ The Tahoe-LAFS read-only capability for the recovery data.
+ This is a capability previously returned by the backup
+ endpoint.
+ responses:
+ 200:
+ description: |
+ Recovery from the backup has been completed.
+ content:
+ application/json:
+ schema:
+ type: "object"
+ property: {}
+
+ /storage-plugins/privatestorageio-zkapauthz-v1/backup:
+ post:
+ description: |
+ Configure ZKAPAuthorizer to maintain an on-grid backup of its state or
+ return the existing configuration details if it has already been
+ configured to do so.
+ responses:
+ 201:
+ description: |
+ A new backup has just been configured. Details about that backup
+ will be returned.
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ recovery-capability:
+ type: "string"
+ description: |
+ The Tahoe-LAFS read-only capability for the recovery
+ data. This is the capability which can be submitted in
+ order to initiate a recovery from the backup.
+
+ 200:
+ description: |
+ A backup has already been configured. Details about that backup
+ will be returned.
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ recovery-capability:
+ type: "string"
+ description: |
+ The Tahoe-LAFS read-only capability for the recovery
+ data. This is the capability which can be submitted in
+ order to initiate a recovery from the backup.
diff --git a/shell.nix b/shell.nix
index c7ed137..be375c6 100644
--- a/shell.nix
+++ b/shell.nix
@@ -17,10 +17,12 @@ let
];
requirements =
''
+ ${builtins.readFile ./docs/requirements.txt}
${builtins.readFile ./requirements/test.in}
${zkapauthorizer.requirements}
'';
};
+
in
pkgs.mkShell {
# Avoid leaving .pyc all over the source tree when manually triggering tests
--
GitLab