openapi: 3.1.0
info:
  title: Cadenza Management API
  summary: 'API for maintenance and distribution of Cadenza Workbook repositories.'
  version: 1.0.0
  description: |
    The Cadenza management API, in its current state, allows automation of recurring repository deployment tasks.
    
    # Errors
    
    Errors are communicated using HTTP standard status codes.
    Some endpoints also provide a more descriptive message in error responses.
    While these error responses might be somewhat human-readable, their format is subject to change and should not be relied on.
    
    # Versioning

    This API follows semantic versioning.
    Any Cadenza major release may introduce a new major version containing breaking changes.
    Cadenza patch releases may introduce new feature versions only.

    There is no plan to support multiple API versions concurrently in a single Cadenza release.

    # Authentication
    
    Requests to the management API may be authenticated by any Cadenza-supported authenticator.
    In most situations, the API key authenticator described in the greater Cadenza developer documentation is recommended, as it fits scripting use cases best.
  contact:
    email: kontakt@disy.net
servers:
  - url: https://{hostname}/{base}/public/adminapi
    variables:
      hostname:
        default: 'localhost:8000'
      base:
        default: trunk

tags:
  - name: repository
    x-displayName: Repositories
    description: Repository maintenance operation
  - name: groups
    x-displayName: User groups and role settings
    description: User groups and role settings maintenance operation

paths:
  /repositories:
    post:
      tags:
        - repository
      summary: 'Import repository from file'
      description: ''
      operationId: repositoryImport
      parameters:
        - $ref: '#/parameters/repository_schema_id'
      requestBody:
        description: ''
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  description: 'Repository-containing zip file'
                  type: string
                  format: binary
              required:
                - file
            encoding:
              file:
                contentType: application/zip

      responses:

        '200':
          description: A pre-existing repository was successfully replaced with content from the import file.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RepositoryImportResponse'
              example:
                repositoryName: uiaenrtd
                replacement: true
                missingGroups: [ a, b, c ]
        '201':
          description: A new repository was created with content from the import file.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RepositoryImportResponse'
              example:
                repositoryName: uiaenrtd
                replacement: false
                missingGroups: [ a, b, c ]

        '400':
          description: |
            Bad request
            * The uploaded file is empty.
            * Missing repository schema id

        '401':
          $ref: '#/components/responses/Unauthorized'

        '403':
          description: Forbidden

        '404':
          $ref: '#/components/responses/NotFound'

        '500':
          description: Internal Server Error

  /repositories/{repositoryName}:
    get:
      tags:
        - repository
      summary: 'Export repository as ZIP file'
      description: |-
        Export a repository as a ZIP file for transport to a different Cadenza instance or storage.
      operationId: repositoryExport
      parameters:
        - $ref: '#/parameters/repository_name'
        - in: query
          name: exportAuthOption
          description: |
            The repository item authorizations to be exported.

            - `none` No authorization information will be exported.
            - `groups` Only permission grants to groups will be exported
            - `groups-users` Permission grants to groups and individual users will be exported, excluding owner information.
            - `groups-users-owners` All permission grants, including owner information, will be exported.
          required: false
          schema:
            type: string
            enum:
              - none
              - groups
              - groups-users
              - groups-users-owners
            default: groups
        - in: query
          name: importerAuthorization
          description: |
            The permissions to assign on import to the importer, if the import creates the repository in the target system.

            - `owner` The importer will become the full owner of the repository, assuming most permissions on the contained items.
            - `manage-content` The importer will receive permissions to manage repository content, allowing him to list items, see their owner, and to delete content.
          required: false
          schema:
            type: string
            enum:
              - owner
              - manage-content
            default: owner
      responses:

        '200':
          description: successful operation
          content:
            application/zip:
              schema:
                type: string
                format: binary

        '401':
          $ref: '#/components/responses/Unauthorized'

        '403':
          description: Forbidden

        '404':
          $ref: '#/components/responses/NotFound'

        '500':
          description: Internal Server Error

    delete:
      tags:
        - repository
      summary: Delete repository
      description: ''
      operationId: repositoryDelete
      parameters:
        - $ref: '#/parameters/repository_name'
      responses:

        '200':
          description: successful operation

        '401':
          $ref: '#/components/responses/Unauthorized'

        '403':
          description: Forbidden

        '404':
          $ref: '#/components/responses/NotFound'

        '500':
          description: Internal Server Error

  /repositories/{repositoryName}/runtestsuite:
    post:
      tags:
        - repository
      summary: Run defined tests for repository
      description: ''
      operationId: runtestsuite
      parameters:
        - $ref: '#/parameters/repository_name'
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationResponse'

        '401':
          $ref: '#/components/responses/Unauthorized'

        '403':
          description: Forbidden

        '404':
          $ref: '#/components/responses/NotFound'

        '500':
          description: Internal Server Error

  /groups:

    post:
      tags:
        - groups
      summary: 'Import user groups and role settings as ZIP file'
      description: |-
        Replaces all user groups and role settings from a ZIP file.
      operationId: groupsImport
      requestBody:
        description: ''
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  description: 'User groups and role settings containing zip file'
                  type: string
                  format: binary
              required:
                - file
            encoding:
              file:
                contentType: application/zip
      responses:

        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupsAndRolesImportResponse'

        '401':
          $ref: '#/components/responses/Unauthorized'

        '403':
          description: Forbidden

        '500':
          description: Internal Server Error

    get:
      tags:
        - groups
      summary: 'Export user groups and role settings as ZIP file'
      description: |-
        Export all user groups and role settings as a ZIP file for transport to a different Cadenza instance or storage.
      operationId: groupsExport
      responses:

        '200':
          description: successful operation
          content:
            application/zip:
              schema:
                type: string
                format: binary

        '401':
          $ref: '#/components/responses/Unauthorized'

        '403':
          description: Forbidden

        '500':
          description: Internal Server Error

parameters:
  repository_schema_id:
    in: query
    name: repositorySchemaId
    description: |-
      Technical name of the target repository database.
      This must match a database repository in `repositoryList.xml` by `databaseRepository/@name`.
      The value is required when more than one repository database is defined in `repositoryList.xml` and the repository does not exist in the target system yet.
    required: false
    schema:
      type: string
  repository_name:
    in: path
    name: repositoryName
    description: Technical repository name
    required: true
    schema:
      type: string

components:

  responses:
    Unauthorized:
      description: |
        Unauthorized
        * Authentication failed

        If using Api-Key authentication, this could mean any of
        * No valid api clients are configured
        * Missing signature parameter
        * Missing requestTimestamp parameter
        * Request is expired
        * Invalid signature

    NotFound:
      description: |
        Not Found
        * Repository does not exist
        * Missing permissions to view the repository

  schemas:
    State:
      type: string
      description: Validation state
      enum:
        - OK
        - WARNING
        - ERROR

    ResourceType:
      type: string
      description: Repository resource type
      enum:
        - DATASOURCE
        - DATASOURCE_VERSION
        - BASIC_OBJECTTYPE
        - COMBINED_OBJECTTYPE
        - COMBINED_OBJECTTYPE_REFERENCE
        - OBJECTTYPE_REFERENCE
        - ATTRIBUTE_REFERENCE
        - HIERARCHY_REFERENCE
        - BASIC_OBJECTTYPE_SOURCE
        - OBJECTTYPE_ATTRIBUTE
        - WORKBOOK
        - DEFAULT_MAP
        - REPOSITORY

    Entry:
      type: object
      properties:
        resourceType:
          $ref: '#/components/schemas/ResourceType'
        description:
          type: string
        state:
          $ref: '#/components/schemas/State'

    ValidationResponse:
      type: object
      properties:
        repositoryName:
          description: Technical repository name
          type: string
        state:
          $ref: '#/components/schemas/State'
        entries:
          type: array
          items:
            $ref: '#/components/schemas/Entry'

    RepositoryImportResponse:
      type: object
      properties:
        repositoryName:
          description: Technical repository name
          type: string
        replacement:
          type: boolean
          example: false
        missingGroups:
          description: 'List of user groups referenced in the imported repository, but not present in the target system'
          type: array
          items:
            type: string

    GroupsAndRolesImportResponse:
      type: object
      properties:
        userGroupsCount:
          description: Numbers of user groups created
          type: int
        systemRolesCount:
          description: Numbers of roles created
          type: int
        groupVariablesCount:
          description: Numbers of variables created
          type: int
