From a5e2f7d70dea20e04e736a13e8f32e5df828a0a3 Mon Sep 17 00:00:00 2001
From: Jean-Paul Calderone <exarkun@twistedmatrix.com>
Date: Mon, 24 Jan 2022 10:41:33 -0500
Subject: [PATCH] fix some formatting issues, improve re-use, add some error
cases
---
docs/source/designs/backup-recovery.yaml | 76 ++++++++++++++----------
1 file changed, 46 insertions(+), 30 deletions(-)
diff --git a/docs/source/designs/backup-recovery.yaml b/docs/source/designs/backup-recovery.yaml
index fd73f61..77c291d 100644
--- a/docs/source/designs/backup-recovery.yaml
+++ b/docs/source/designs/backup-recovery.yaml
@@ -1,36 +1,46 @@
openapi: "3.1.0"
info:
title: "Backup / Recovery"
- description: |
+ description: >-
This API allows backup and recovery of ZKAPAuthorizer internal state.
version: "1.0.0"
paths:
/storage-plugins/privatestorageio-zkapauthz-v1/recover:
post:
- description: |
+ 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.
+ $ref: "#/definitions/BackupConfiguration"
responses:
- 200:
- description: |
- Recovery from the backup has been completed.
+ "500":
+ description: >-
+ Recovery from the backup has failed for some reason.
+ content:
+ application/json:
+ schema:
+ $ref: "#/definitions/ErrorResponse"
+
+ "404":
+ description: >-
+ Recovery from the backup has failed because the recovery data
+ cannot be retrieved using the given capability.
+ content:
+ application/json:
+ schema:
+ $ref: "#/definitions/ErrorResponse"
+
+ "200":
+ description: >-
+ Recovery from the backup has succeeded.
content:
application/json:
schema:
type: "object"
- property: {}
+ properties: {}
/storage-plugins/privatestorageio-zkapauthz-v1/backup:
post:
@@ -46,14 +56,7 @@ paths:
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.
+ $ref: "#/definitions/BackupConfiguration"
200:
description: |
@@ -62,11 +65,24 @@ paths:
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.
+ $ref: "#/definitions/BackupConfiguration"
+
+definitions:
+ BackupConfiguration:
+ 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.
+
+ ErrorResponse:
+ type: "object"
+ properties:
+ details:
+ type: "string"
+ description: >-
+ A free-form text field which may give further details about the
+ failure.
--
GitLab