backup-recovery.yaml

openapi: "3.0.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:
              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.
      responses:
        "500":
          description: >-
            Recovery from the backup has failed for some reason.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

        "404":
          description: >-
            Recovery from the backup has failed because the recovery data
            cannot be retrieved using the given capability.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

        "200":
          description: >-
            Recovery from the backup has succeeded.
          content:
            application/json:
              schema:
                type: "object"
                properties: {}

  /storage-plugins/privatestorageio-zkapauthz-v1/backup:
    get:
      description: >-
        Retrieve information about the backup configuration and state of this
        node.
      responses:
        200:
          description: >-
            Information about backup configuration is available and included
            in the response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BackupConfiguration"
    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:
                $ref: "#/components/schemas/BackupConfiguration"

        200:
          description: |
            A backup has already been configured.  Details about that backup
            will be returned.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BackupConfiguration"

components:
  schemas:
    Error:
      type: "object"
      properties:
        details:
          type: "string"
          description: >-
            A free-form text field which may give further details about
            the failure.

    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.



  responses:
    ErrorResponse:
      description: >-
        Something broken.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"