backup-recovery.yaml

openapi: "3.0.0"

info:
  title: "Replication / Recovery"
  description: >-
    This API allows replication and recovery of ZKAPAuthorizer internal state.
    Replication is in a single direction from this single Tahoe-LAFS node to
    the Tahoe-LAFS grid.
  version: "1.0.0"

paths:
  /storage-plugins/privatestorageio-zkapauthz-v1/recover:
    post:
      description: >-
        Recover ZKAPAuthorizer state from a previously configured replica.
        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 replica.
      responses:
        "500": # INTERNAL SERVER ERROR
          description: >-
            Recovery from the replica has failed for some reason.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

        "409": # CONFLICT
          description: >-
            Recovery is not possible at this time because local state already
            exists in the database.  Recover into a new, empty ZKAPAuthorizer
            installation only.

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

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

  /storage-plugins/privatestorageio-zkapauthz-v1/replicate:
    get:
      description: >-
        Retrieve information about the replica configuration and state of this
        node.
      responses:
        200: # Ok
          description: >-
            Information about replica configuration is available and included
            in the response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReplicaConfiguration"
    post:
      description: |
        Configure ZKAPAuthorizer to maintain an on-grid replica of its state
        or return the existing configuration details if it has already been
        configured to do so.
      responses:
        201: # Created
          description: |
            The replication system is now configured.  The response includes
            the recovery capability for the replica that is being maintained.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReplicaConfiguration"

        409: # Conflict
          description: |
            The replication system was already configured.  The response
            includes the recovery capability for the replica that is being
            maintained.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReplicaConfiguration"

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

    ReplicaConfiguration:
      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 replica.



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