################################################################################
# SEAL Systems AG
# SEAL Operator
# REST API - OpenAPI 2.0 Definition
# $id:
#
# (c) SEAL Systems AG 2017
################################################################################
swagger: '2.0'
info:
  title: SEAL Operator REST API
  description:
    This is the REST API of the SEAL Operator System. It is used by the
    graphical front and may also be used for integration purposes.
  version: "0.5"
  license:
    name: Requires SEAL Operator License (Proprietary)
    url: https://sealsystems.de/products/operator
  contact:
    name: SEAL Systems AG, Röttenbach, Germany
    url: https://sealsystems.de/
    email: sales@sealsystems.de

# Communication Basics
host: localhost:3008
schemes:
  - https
basePath: /v1
consumes:
  - application/json
produces:
  - application/json

# Authentication schemes
securityDefinitions:
  oauth:
    type: oauth2
    authorizationUrl: https://your.auth.host/your/auth/path
    tokenUrl: https://your.auth.host/your/token/path
    flow: accessCode
    scopes:
      authN: User is authenticated

paths:

# ==============================================================================
# SERVICES
# ==============================================================================
  /services:
    get:
      summary: Get list of available services
      description: |
        A GET call to this route will return a list of active services
        currently available through the API.
      tags:
        - Services
#      parameters:
#        - name: query
#          description: |
#            Query string for searching services. Use ? and * as wildcards.
#          in: query
#          type: string
      responses:
        200:
          description: OK, collection of services is returned.
          schema:
            type: array
            items:
              $ref: '#/definitions/Service'
        401:
          description: Unauthorized (Auth token invalid)
          schema:
            $ref: '#/definitions/Error'
        403:
          description: |
            Forbidden. The user lacks acces rights to access the service list.
          schema:
            $ref: '#/definitions/Error'
        500:
          description: Application Error
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - oauth:
          - authN
# ==============================================================================
  /services/{sid}:
    get:
      summary: Retrieve service metadata
      description: |
        FIXME
      tags:
        - Services
      parameters:
        - name: sid
          in: path
          type: string
          required: true
          description: ID of the current service.
      responses:
        200:
          description: OK, service metadata is returned
          schema:
            $ref: '#/definitions/Service'
        401:
          description: Unauthorized (Auth token invalid)
          schema:
            $ref: '#/definitions/Error'
        403:
          description: |
            Forbidden. The user lacks acces rights to access the service metadata.
          schema:
            $ref: '#/definitions/Error'
        404:
          description: The requested Service was not found.
          schema:
            $ref: '#/definitions/Error'
        500:
          description: Application Error
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - oauth:
          - authN
# ==============================================================================
# Document Repository
# ==============================================================================
  /services/{sid}/repo:
    get:
      summary: Access the document repository within a service
      description: |
        Some services (not all) expose access to documents.
        All documents available through a Service are accessible via the 'repo'
        route. This route provides access to the repository root collection,
        containing documents and/or child collections. Use metadata property
        names and regular expressions in URL query string to search for entries
        (documents or collections) and the offset and limit parameters to control
        the number of results returned.
      tags:
        - Documents
        - Collections
      parameters:
        - name: sid
          in: path
          type: string
          required: true
          description: ID of the current repository.
        - name: offset
          type: integer
          in: query
          default: 0
          description: Index of first result to return.
        - name: limit
          type: integer
          in: query
          default: 50
          description: Number of results to return. Maximum is 500.
        - name: sort
          type: string
          in: query
          description: |
            Sort query results. Comma separated list of property names, prefixed with '-'
            for descending sort order. Example: 'sort=date,-name'
        - name: scope
          type: string
          in: query
          default: 'all'
          description: |
            Set the scope when searching for documents. Possible values are `root`
            and `all`, default is `all`.
        - name: embed
          type: string
          in: query
          description: |
            Include sub-ressource or sub-collection data in response.
            "permissions": include access rights records for each entry.
            "thumb": include base64 encoded thumbnail image for each entry, e.g.
            ```
            "embedded": {
              "content-type": "image/png"
              "thumb": "A9cX0..."
            }
            ```
      responses:
        200:
          description: OK, collection of entries is returned.
          schema:
            type: array
            items:
              $ref: '#/definitions/RepoEntry'
        401:
          description: Unauthorized (Auth token invalid)
          schema:
            $ref: '#/definitions/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          schema:
            $ref: '#/definitions/Error'
        404:
          description: The service does not provide a repository
          schema:
            $ref: '#/definitions/Error'
        500:
          description: Application Error
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - oauth:
          - authN
# ------------------------------------------------------------------------------
    post:
      summary: Create new entry in the root collection of the repository.
      description: |
        Creates a new record in the current Repository, inside the
        root collection, and assigns the posted metadata.
      tags:
        - Documents
        - Collections
      parameters:
        - name: sid
          in: path
          type: string
          required: true
          description: ID of the current service.
        - name: metadata
          in: body
          required: true
          description: metadata of the entry to be created
          schema:
            $ref: '#/definitions/BaseRepoEntry'
      responses:
        200:
          description: OK, entry created. Entry metadata returned.
          schema:
            $ref: '#/definitions/RepoEntry'
        401:
          description: Unauthorized (Auth token invalid)
          schema:
            $ref: '#/definitions/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          schema:
            $ref: '#/definitions/Error'
        404:
          description: The service does not provide a repository
          schema:
            $ref: '#/definitions/Error'
        409:
          description: |
            Conflict, ressource could not be created. See error message for
            details.
          schema:
            $ref: '#/definitions/Error'
        500:
          description: Application Error
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - oauth:
          - authN
# ==============================================================================
  /services/{sid}/repo/command:
    post:
      summary: Create new command resource.
      description: |
        Creates a new record in the command resource. It returns a JSON object
        containing a command id for tracking status of asynchronous commands.
      tags:
        - Documents
        - Collections
      parameters:
        - name: sid
          in: path
          type: string
          required: true
          description: ID of the current service.
        - name: command
          in: body
          required: true
          description: |
            The command entry and it's parameter to be created. Currently supported
             commands are `copy` and `move`. The parameters for both commands:
            ```json
            {
              "action": "copy|move",
              "parameter": {
                "source": "source href",
                "parent": "uuid of target parent"
              }
            }
            ```
            The source may be a remote repository in later implementations, so an `href` is needed here.
          schema:
            $ref: '#/definitions/Command'
      responses:
        200:
          description: OK, entry created. Command id will be returned.
          schema:
            $ref: '#/definitions/CommandStatus'
        401:
          description: Unauthorized (Auth token invalid)
          schema:
            $ref: '#/definitions/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          schema:
            $ref: '#/definitions/Error'
        404:
          description: The service does not provide commands
          schema:
            $ref: '#/definitions/Error'
        409:
          description: |
            Conflict, ressource could not be created. See error message for
            details.
          schema:
            $ref: '#/definitions/Error'
        500:
          description: Application Error
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - oauth:
          - authN
# ==============================================================================
  /services/{sid}/repo/command/{cid}:
    get:
      summary: Access a command resource within a service
      description: |
        Returns a JSON object containing the status of the command. Command resources
        are automatically deleted after a final state (success or failure) was delivered
        once to the client or it's expired.
      tags:
        - Documents
        - Collections
      parameters:
        - name: sid
          in: path
          type: string
          required: true
          description: ID of the current service.
        - name: cid
          in: path
          type: string
          required: true
          description: ID of the command.
      responses:
        200:
          description: OK, status of command resource is returned
          schema:
            $ref: '#/definitions/CommandStatus'
        401:
          description: Unauthorized (Auth token invalid)
          schema:
            $ref: '#/definitions/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          schema:
            $ref: '#/definitions/Error'
        404:
          description: The service does not provide the given resource.
          schema:
            $ref: '#/definitions/Error'
        500:
          description: Application Error
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - oauth:
          - authN
# ==============================================================================
  /services/{sid}/repo/{uuid}:
    get:
      summary: Retrieve metadata of a specific entry (document or collection).
      description: |
        Given a 'uuid' parameter, this route retrieves an entry's
        metadata. The entry may be either a document or a collection.
      tags:
        - Documents
        - Collections
      parameters:
        - name: sid
          in: path
          type: string
          required: true
          description: ID of the current service.
        - name: uuid
          in: path
          type: string
          required: true
          description: ID of the repository entry
      responses:
        200:
          description: OK, entry metadata returned.
          schema:
            $ref: '#/definitions/RepoEntry'
        401:
          description: Unauthorized (Auth token invalid)
          schema:
            $ref: '#/definitions/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          schema:
            $ref: '#/definitions/Error'
        404:
          description: The given uuid was not found.
          schema:
            $ref: '#/definitions/Error'
        500:
          description: Application Error
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - oauth:
          - authN
# ------------------------------------------------------------------------------
    put:
      summary: Update entry metadata (complete, replace)
      description: |
        Completely replace the metadata record of the given entry.
        Only record metadata can be replaced; internal auto-generated metadata
        (links, embedded), if given, are ignored.
      tags:
        - Documents
        - Collections
      parameters:
        - name: sid
          in: path
          type: string
          required: true
          description: ID of the current repository.
        - name: uuid
          in: path
          type: string
          required: true
          description: UUID of the entry
        - name: metadata
          in: body
          required: true
          description: |
            New entry metadata. Note that changing the entry type is not
            possible by updating metadata.
          schema:
            $ref: '#/definitions/BaseRepoEntry'
      responses:
        200:
          description: OK, entry metadata replaced, new metadata returned.
          schema:
            $ref: '#/definitions/RepoEntry'
        401:
          description: Unauthorized (Auth token invalid)
          schema:
            $ref: '#/definitions/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          schema:
            $ref: '#/definitions/Error'
        404:
          description: No entry found under the given 'uuid'.
          schema:
            $ref: '#/definitions/Error'
        409:
          description: |
            Conflict, resource could not be updated. See error message for
            details.
          schema:
            $ref: '#/definitions/Error'
        500:
          description: Application Error
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - oauth:
          - authN
# ------------------------------------------------------------------------------
    patch:
      summary: Update entry metadata (partial, merge)
      description: |
        Update the given entry's metadata. Only data given with the patch will
        be changed/added; no entries removed. Only core metadata can be
        updated; internal auto-generated metadata (links, embedded),
        if given, are ignored.
      tags:
        - Documents
        - Collections
      parameters:
        - name: sid
          in: path
          type: string
          required: true
          description: ID of the current service.
        - name: uuid
          in: path
          type: string
          required: true
          description: UUID of the entry
        - name: metadata
          in: body
          required: true
          description: New entry metadata.
          schema:
            $ref: '#/definitions/BaseRepoEntry'
      responses:
        200:
          description: OK, entry metadata replaced, new metadata returned.
          schema:
            $ref: '#/definitions/RepoEntry'
        401:
          description: Unauthorized (Auth token invalid)
          schema:
            $ref: '#/definitions/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          schema:
            $ref: '#/definitions/Error'
        404:
          description: No entry found at the given 'uuid'.
          schema:
            $ref: '#/definitions/Error'
        409:
          description: |
            Conflict, resource could not be updated. See error message for
            details.
          schema:
            $ref: '#/definitions/Error'
        500:
          description: Application Error
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - oauth:
          - authN
# ------------------------------------------------------------------------------
    post:
      summary: Create a new entry in the current collection (collections only).
      description: |
        If the entry under the given uuid is a collection, then a POST request
        to this route will create a new entry in this collection. Whether the
        created entry will be a document or another collection depends on the
        metadata enclosed in the request body. See RepoEntry data model.
      tags:
        - Collections
      parameters:
        - name: sid
          in: path
          type: string
          required: true
          description: ID of the current Service.
        - name: uuid
          in: path
          type: string
          required: true
          description: UUID of the collection
        - name: metadata
          in: body
          required: true
          description: Metadata of the entry to create
          schema:
            $ref: '#/definitions/BaseRepoEntry'
      responses:
        200:
          description: OK, new entry created, metadata of the entry returned.
          schema:
            $ref: '#/definitions/RepoEntry'
        401:
          description: Unauthorized (Auth token invalid)
          schema:
            $ref: '#/definitions/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          schema:
            $ref: '#/definitions/Error'
        404:
          description: No entry found at the given 'uuid'.
          schema:
            $ref: '#/definitions/Error'
        405:
          description: |
            Method not allowed. The entry under 'uuid' is not a collection.
          schema:
            $ref: '#/definitions/Error'
        409:
          description: |
            Conflict, resource could not be updated. See error message for
            details.
          schema:
            $ref: '#/definitions/Error'
        500:
          description: Application Error
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - oauth:
          - authN
# ------------------------------------------------------------------------------
    delete:
      summary: Delete the current entry.
      description: |
        Removes the current entry from the repository. This will not only
        remove the reference within Operator, but the actual record and content
        in the target system.
      tags:
        - Documents
        - Collections
      parameters:
        - name: sid
          in: path
          type: string
          required: true
          description: ID of the current Service.
        - name: uuid
          in: path
          type: string
          required: true
          description: UUID of the entry to delete
        - name: force
          in: query
          type: boolean
          required: false
          description: Delete document even if it's still in use by one or more tasks.
      responses:
        204:
          description: OK, entry was deleted.
        401:
          description: Unauthorized (Auth token invalid)
          schema:
            $ref: '#/definitions/Error'
        403:
          description: Forbidden (deletion refused by target system)
          schema:
            $ref: '#/definitions/Error'
        404:
          description: Entry under 'uuid' was not found.
          schema:
            $ref: '#/definitions/Error'
        409:
          description: |
            Conflict, resource could not be deleted. Returns collection of tasks
            using the current document.
          schema:
            type: array
            items:
              $ref: '#/definitions/Task'
        500:
          description: Application Error
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - oauth:
          - authN
# ==============================================================================
  /services/{sid}/repo/{uuid}/children:
    get:
      summary: Access a collections children.
      description: |
        Some services (not all) expose access to documents.
        All documents available through a Service are accessible via the 'repo'
        route. This route provides access to the children of a collection, containing
        documents and/or collections. Use metadata property names and regular
        expressions in URL query string to search for entries (documents or collections)
        ae offset and limit parameters to control the number of results returned.
      tags:
        - Collections
      parameters:
        - name: sid
          in: path
          type: string
          required: true
          description: ID of the current repository.
        - name: uuid
          in: path
          type: string
          required: true
          description: UUID of the parent collection
        - name: offset
          type: integer
          in: query
          default: 0
          description: Index of first result to return.
        - name: limit
          type: integer
          in: query
          default: 50
          description: Number of results to return. Maximum is 500.
        - name: sort
          type: string
          in: query
          description: |
            Sort query results. Comma separated list of property names, prefixed with '-'
            for descending sort order. Example: 'sort=date,-name'
        - name: embed
          type: string
          in: query
          description: |
            Include sub-ressource or sub-collection data in response.
            "permissions": include access rights records for each entry.
            "icon": include icon-font and value for each entry, e.g.
            ```
            "embedded": {
              "icon": "material:play"
            }
            ```
            "thumb": include base64 encoded thumbnail image for each entry, e.g.
            ```
            "embedded": {
              "content-type": "image/png"
              "thumb": "A9cX0..."
            }
            ```
      responses:
        200:
          description: OK, collection of entries is returned.
          schema:
            type: array
            items:
              $ref: '#/definitions/RepoEntry'
        401:
          description: Unauthorized (Auth token invalid)
          schema:
            $ref: '#/definitions/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          schema:
            $ref: '#/definitions/Error'
        404:
          description: The service does not provide a repository
          schema:
            $ref: '#/definitions/Error'
        500:
          description: Application Error
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - oauth:
          - authN
# ==============================================================================
  /services/{sid}/repo/{uuid}/content:
    get:
      summary: Retrieve binary content (documents only)
      description: |
        If the entry under 'uuid' is a document, then this route provides access
        to the binary content (i.e. the actual file).
      tags:
        - Documents
      produces:
        - application-octed/stream
      parameters:
        - name: sid
          in: path
          type: string
          required: true
          description: ID of the current Service.
        - name: uuid
          in: path
          type: string
          required: true
          description: UUID of the document
      responses:
        200:
          description: OK, content is returned.
        401:
          description: Unauthorized (Auth token invalid)
          schema:
            $ref: '#/definitions/Error'
        403:
          description: |
            Forbidden. The user lacks acces rights to read the binary content.
          schema:
            $ref: '#/definitions/Error'
        404:
          description: |
            Not found. Either no entry was found under the given 'uuid', or the
            entry is not a document, or the document has no binary content (yet).
            See error message for details.
          schema:
            $ref: '#/definitions/Error'
        500:
          description: Application Error
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - oauth:
          - authN
# ------------------------------------------------------------------------------
    put:
      summary: Create or update document binary content (documents only)
      description: |
        Upload binary content of a document. Create if none exists, or
        replace existing file. Uploading binary content to collection type
        entries is not supported.
      consumes:
        - multipart/form-data
      tags:
        - Documents
      parameters:
        - name: sid
          in: path
          type: string
          required: true
          description: ID of the current service.
        - name: uuid
          in: path
          type: string
          required: true
          description: UUID of the document
        - name: content
          in: formData
          required: true
          description: binary data for upload
          type: file
      responses:
        204:
          description: OK, content was updated.
        401:
          description: Unauthorized (Auth token invalid)
          schema:
            $ref: '#/definitions/Error'
        403:
          description: |
            Forbidden. The user lacks acces rights to update the binary content.
          schema:
            $ref: '#/definitions/Error'
        404:
          description: No entry was found under the given 'uuid'.
          schema:
            $ref: '#/definitions/Error'
        406:
          description: |
            Method not allowed. The entry under 'uuid' is not a document, or the
            document does not support changing of the bianry content.
          schema:
            $ref: '#/definitions/Error'
        409:
          description: |
            Conflict, resource could not be updated. See error message for
            details.
          schema:
            $ref: '#/definitions/Error'
        500:
          description: Application Error
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - oauth:
          - authN
# ------------------------------------------------------------------------------
    delete:
      summary: Delete document binary content (documents only)
      description: |
        Deletes the binary content of a document, leaving metadata only.
        Note that some repositories will not allow this operation. To delete
        binary content from such repositories, you will need to delete the entire
        document. Deleting binary content is not supported by collection type
        entries.
      tags:
        - Documents
      parameters:
        - name: sid
          in: path
          type: string
          required: true
          description: ID of the current service.
        - name: uuid
          in: path
          type: string
          required: true
          description: UUID of the document
      responses:
        204:
          description: OK, content was deleted.
        401:
          description: Unauthorized (Auth token invalid)
          schema:
            $ref: '#/definitions/Error'
        403:
          description: |
            Forbidden. The user lacks acces rights to delete the binary content.
          schema:
            $ref: '#/definitions/Error'
        404:
          description: No binary content found.
          schema:
            $ref: '#/definitions/Error'
        405:
          description: |
            Method not allowed. Either the entry under 'uuid' is not a document,
            or it does not support deleting of the binary content. See error
            message for details.
          schema:
            $ref: '#/definitions/Error'
        409:
          description: |
            Conflict, resource could not be deleted. Returns collection of tasks
            using the current document.
          schema:
            type: array
            items:
              $ref: '#/definitions/Task'
        500:
          description: Application Error
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - oauth:
          - authN
  # ==============================================================================
  /services/{sid}/repo/{uuid}/preview:
    get:
      summary: Retrieve preview of binary content (documents only)
      description: |
        If the entry under 'uuid' is a document, then this route provides access
        to the preview content.
      tags:
        - Documents
      produces:
        - image/jpeg
      parameters:
        - name: sid
          in: path
          type: string
          required: true
          description: ID of the current Service.
        - name: uuid
          in: path
          type: string
          required: true
          description: UUID of the document
      responses:
        200:
          description: OK, preview is returned.
        401:
          description: Unauthorized (Auth token invalid)
          schema:
            $ref: '#/definitions/Error'
        403:
          description: |
            Forbidden. The user lacks acces rights to read the binary content.
          schema:
            $ref: '#/definitions/Error'
        404:
          description: |
            Not found. Either no entry was found under the given 'uuid', or the
            entry is not a document, or the document has no binary content, or the
            preview is not created (so far). See error message for details.
          schema:
            $ref: '#/definitions/Error'
        500:
          description: Application Error
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - oauth:
          - authN

# ==============================================================================
# Tasks
# ==============================================================================
  /tasks:
      get:
        summary: Retrieve collection of tasks managed by all services.
        description: |
          This route provides access to the root collection of known tasks for all services supporting tasks.
          Use property names and regular expressions in URL query string to search for tasks.
          Use the 'embed' parameter to include information about instances and sub-ressources.
          Use the 'inputDocument' parameter to search for a task containing a special document and use 'inlineCount'
          to get the number of found tasks.
        tags:
          - Tasks
        parameters:
          - name: inputDocument
            type: string
            in: query
            description: A document UUID queried for in all lists of input documents of all tasks.
          - name: embed
            type: string
            in: query
            description: |
              Information about sub-collections and/or sub-ressources to include
              in the response.
              - "permissions": include user access rights for each Task
              - "metadata": include Task metadata.
              - "input": include input lists (metadata only)
              - "output": include output lists (metadata only)
              - "cstats": connector specific job id's and states
          - name: inlineCount
            type: boolean
            in: query
            description: |
              Return a JSON object containing the number of tasks found, according to the query parameters, instead of an array with tasks.
        responses:
          200:
            description: |
              OK, collection of tasks or count is returned. Example for count:
              ```
              {
                count: 0
              }
              ```
            schema:
              type: array
              items:
                $ref: '#/definitions/Task'
          401:
            description: Unauthorized (Auth token invalid)
            schema:
              $ref: '#/definitions/Error'
          403:
            description: |
              Forbidden. The user lacks rights to access the data.
            schema:
              $ref: '#/definitions/Error'
          404:
            description: Not found
            schema:
              $ref: '#/definitions/Error'
          500:
            description: Application Error
            schema:
              $ref: '#/definitions/Error'
          default:
            description: Unexpected error
            schema:
              $ref: '#/definitions/Error'
        security:
          - oauth:
            - authN
  # ------------------------------------------------------------------------------
  /services/{sid}/tasks:
    get:
      summary: Retrieve collection of tasks managed by the service.
      description: |
        This route provides access to the root collection of known tasks for
        the current service.
        Use property names and regular expressions in URL query string to search
        for tasks and the offset and limit parameters to control the number of
        results returned.
        Use the 'embed' parameter to include information about instances and
        sub-ressources.
      tags:
        - Tasks
      parameters:
        - name: sid
          type: string
          in: path
          required: true
          description: ID of the Service managing the tasks
        - name: offset
          type: integer
          in: query
          default: 0
          description: Index of first result to return.
        - name: limit
          type: integer
          in: query
          default: 50
          description: Number of results to return. Maximum is 500.
        - name: sort
          type: string
          in: query
          description: |
            Sort query results. Comma separated list of property names, prefixed with '-'
            for descending sort order. Example: 'sort=date,-name'
        - name: inputDocument
          type: string
          in: query
          description: A document UUID queried for in all lists of input documents of all tasks.
        - name: embed
          type: string
          in: query
          description: |
            Information about sub-collections and/or sub-ressources to include
            in the response.
            - "permissions": include user access rights for each Task
            - "metadata": include Task metadata.
            - "input": include input lists (metadata only)
            - "output": include output lists (metadata only)
            - "cstats": connector specific job id's and states
        - name: inlineCount
          type: boolean
          in: query
          description: |
            Return a JSON object containing the number of tasks found, according to the query parameters, instead of an array with tasks.
      responses:
        200:
          description: |
            OK, collection of tasks or count is returned. Example for count:
            ```
            {
              count: 0
            }
            ```
          schema:
            type: array
            items:
              $ref: '#/definitions/Task'
        401:
          description: Unauthorized (Auth token invalid)
          schema:
            $ref: '#/definitions/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          schema:
            $ref: '#/definitions/Error'
        404:
          description: Not found
          schema:
            $ref: '#/definitions/Error'
        500:
          description: Application Error
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - oauth:
          - authN
# ------------------------------------------------------------------------------
    post:
      summary: Create new task.
      description: |
        Adds a new Task to the collection. Given metadata is assigned,
        input list must be filled after creation.
      tags:
        - Tasks
      parameters:
        - name: sid
          type: string
          in: path
          required: true
          description: ID of the Service managing the current Task
        - name: task
          in: body
          required: true
          description: Task metadata
          schema:
            $ref: '#/definitions/Task'
      responses:
        200:
          description: OK, task created. Task metadata returned.
          schema:
            $ref: '#/definitions/Task'
        401:
          description: Unauthorized (Auth token invalid)
          schema:
            $ref: '#/definitions/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          schema:
            $ref: '#/definitions/Error'
        404:
          description: Not found
          schema:
            $ref: '#/definitions/Error'
        409:
          description: |
            Conflict, resource could not be created. See error message for
            details.
          schema:
            $ref: '#/definitions/Error'
        500:
          description: Application Error
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - oauth:
          - authN
# ==============================================================================
  /services/{sid}/tasks/{tid}:
    get:
      summary: Retrieve metadata of current task.
      description: |
        This route provides access to a Task's root record. The record
        contains taks metadata (such as parameters controlling it), details
        are available via sub-ressources and sub-collections.
      tags:
        - Tasks
      parameters:
        - name: sid
          type: string
          in: path
          required: true
          description: ID of the Service managing the current Task
        - name: tid
          in: path
          type: string
          required: true
          description: ID of the current task.
        - name: embed
          in: query
          type: string
          description: |
            Embed sub-ressources in the response.
            - "input": include list of input documents
            - "output": include list of output documents
        - name: force
          in: query
          type: boolean
          description: Force status update from backend system.
      responses:
        200:
          description: OK. Task metadata returned.
          schema:
            $ref: '#/definitions/Task'
        401:
          description: Unauthorized (Auth token invalid)
          schema:
            $ref: '#/definitions/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          schema:
            $ref: '#/definitions/Error'
        404:
          description: Not found
          schema:
            $ref: '#/definitions/Error'
        500:
          description: Application Error
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - oauth:
          - authN
# ------------------------------------------------------------------------------
    put:
      summary: Update task metadata (complete, replace)
      description: |
        A put call to the task root record completely replaces task metadata,
        but does not affect sub-ressources or sub-collections.
      tags:
        - Tasks
      parameters:
        - name: sid
          type: string
          in: path
          required: true
          description: ID of the Service managing the current Task
        - name: tid
          in: path
          type: string
          required: true
          description: ID of the task to update.
        - name: update
          in: body
          description: New metadata for the task
          required: true
          schema:
            $ref: '#/definitions/TaskMetadata'
      responses:
        200:
          description: OK, task updated and returned.
          schema:
            $ref: '#/definitions/Task'
        401:
          description: Unauthorized (Auth token invalid)
          schema:
            $ref: '#/definitions/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          schema:
            $ref: '#/definitions/Error'
        404:
          description: Not found
          schema:
            $ref: '#/definitions/Error'
        409:
          description: |
            Conflict, resource could not be updated. See error message for
            details.
          schema:
            $ref: '#/definitions/Error'
        500:
          description: Application Error
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - oauth:
          - authN
# ------------------------------------------------------------------------------
    patch:
      summary: Update Task metadata (partial, merge)
      description: |
        Does a partial update to the Task metadata. Given metadata replaces
        existing one, or is added to the record if not yet present. No metadata
        is deleted.
      tags:
        - Tasks
      parameters:
        - name: sid
          type: string
          in: path
          required: true
          description: ID of the Service managing the current Task
        - name: tid
          in: path
          type: string
          required: true
          description: ID of the Task to update.
        - name: Update
          in: body
          description: New metadata for the task
          required: true
          schema:
            $ref: '#/definitions/TaskMetadata'
      responses:
        200:
          description: OK, task updated and returned.
          schema:
            $ref: '#/definitions/Task'
        401:
          description: Unauthorized (Auth token invalid)
          schema:
            $ref: '#/definitions/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          schema:
            $ref: '#/definitions/Error'
        404:
          description: Not found
          schema:
            $ref: '#/definitions/Error'
        409:
          description: |
            Conflict, resource could not be updated. See error message for
            details.
          schema:
            $ref: '#/definitions/Error'
        500:
          description: Application Error
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - oauth:
          - authN
# ------------------------------------------------------------------------------
    delete:
      summary: Delete a Task.
      description: |
        Deletes a Task from the collection. This is only possible if the Task
        is not currently active and if the user has sufficient access rights.
      tags:
        - Tasks
      parameters:
        - name: sid
          type: string
          in: path
          required: true
          description: ID of the Service managing the current Task
        - name: tid
          in: path
          type: string
          required: true
          description: ID of the Task to delete.
      responses:
        204:
          description: OK. Task deleted.
        401:
          description: Unauthorized (Auth token invalid)
          schema:
            $ref: '#/definitions/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          schema:
            $ref: '#/definitions/Error'
        404:
          description: Not found
          schema:
            $ref: '#/definitions/Error'
        409:
          description: |
            Conflict. Task cannot be deleted because it is currently active.
          schema:
            $ref: '#/definitions/Error'
        500:
          description: Application Error
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - oauth:
          - authN
# ==============================================================================
  /services/{sid}/tasks/{tid}/action:
    post:
      summary: Trigger an action
      description: |
        Trigger a new action on the current task. Currently supported
        actions are `start`, `abort`, `pause` and `resume`.
      tags:
        - Tasks
      parameters:
        - name: sid
          in: path
          type: string
          required: true
          description: ID of the current service.
        - name: tid
          in: path
          type: string
          required: true
          description: ID of the current task.
        - name: action
          in: body
          required: true
          description: |
            The body contains a JSON object with the name of the action.
          schema:
            $ref: '#/definitions/Action'
      responses:
        204:
          description: OK, action started.
        401:
          description: Unauthorized (Auth token invalid)
          schema:
            $ref: '#/definitions/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          schema:
            $ref: '#/definitions/Error'
        404:
          description: The service does not provide actions
          schema:
            $ref: '#/definitions/Error'
        409:
          description: |
            Conflict, action could not be triggered. See error message for
            details.
          schema:
            $ref: '#/definitions/Error'
        500:
          description: Application Error
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - oauth:
          - authN
# ==============================================================================
  /services/{sid}/tasks/{tid}/input:
    get:
      summary: Retrieve list of task input items
      description: |
        This route provides access to a Task's list of input documents. Input
        lists of Tasks are structure-wise identical with Lists in general,
        they differ in that they are Task-internal and hence not available via
        the /lists route. Input lists can have list-level metadata, and each
        list item can have metadata as well.
        A call to this route will provide the list-level metadata and an
        inventory of the collection. Access input list items via the 'items'
        sub-collection. Use the 'embed' parameter to include item metadata
        in the result.
      tags:
        - Tasks
      parameters:
        - name: sid
          type: string
          in: path
          required: true
          description: ID of the Service managing the current Task
        - name: tid
          in: path
          type: string
          required: true
          description: ID of the current task.
        - name: embed
          type: string
          in: query
          description: |
            Use 'embed' to include sub-collection metadata in the result.
            - "items": Include list-item metadata.
      responses:
        200:
          description: OK, collection of input list items returned
          schema:
            $ref: '#/definitions/List'
        401:
          description: Unauthorized (Auth token invalid)
          schema:
            $ref: '#/definitions/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          schema:
            $ref: '#/definitions/Error'
        404:
          description: Not found
          schema:
            $ref: '#/definitions/Error'
        500:
          description: Application Error
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - oauth:
          - authN
# ------------------------------------------------------------------------------
    put:
      summary: Update input list metadata (complete, replace)
      description: |
        A put call to the input list root record completely replaces the metadata,
        but does not affect sub-collections.
      tags:
        - Tasks
      parameters:
        - name: sid
          type: string
          in: path
          required: true
          description: ID of the Service managing the current Task
        - name: tid
          in: path
          type: string
          required: true
          description: ID of the task to update.
        - name: update
          in: body
          description: New metadata for the task input list
          required: true
          schema:
            $ref: '#/definitions/TaskMetadata'
      responses:
        200:
          description: OK, input list updated and returned.
          schema:
            $ref: '#/definitions/List'
        401:
          description: Unauthorized (Auth token invalid)
          schema:
            $ref: '#/definitions/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          schema:
            $ref: '#/definitions/Error'
        404:
          description: Not found
          schema:
            $ref: '#/definitions/Error'
        409:
          description: |
            Conflict, resource could not be updated. See error message for
            details.
          schema:
            $ref: '#/definitions/Error'
        500:
          description: Application Error
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - oauth:
          - authN
# ------------------------------------------------------------------------------
    patch:
      summary: Update input list metadata (partial, merge)
      description: |
        Does a partial update to the input list metadata. Given metadata replaces
        existing one, or is added to the record if not yet present. No metadata
        is deleted.
      tags:
        - Tasks
      parameters:
        - name: sid
          type: string
          in: path
          required: true
          description: ID of the Service managing the current Task
        - name: tid
          in: path
          type: string
          required: true
          description: ID of the Task to update.
        - name: embed
          type: string
          in: query
          description: |
            Use 'embed' to include sub-collection metadata for updating.
            - "items": Include list-item data including indices for reordering.
        - name: Update
          in: body
          description: New metadata for the input list.
          required: true
          schema:
            $ref: '#/definitions/List'
      responses:
        200:
          description: OK, input list updated and returned.
          schema:
            $ref: '#/definitions/List'
        401:
          description: Unauthorized (Auth token invalid)
          schema:
            $ref: '#/definitions/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          schema:
            $ref: '#/definitions/Error'
        404:
          description: Not found
          schema:
            $ref: '#/definitions/Error'
        409:
          description: |
            Conflict, resource could not be updated. See error message for
            details.
          schema:
            $ref: '#/definitions/Error'
        500:
          description: Application Error
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - oauth:
          - authN
# ------------------------------------------------------------------------------
    post:
      summary: Append a new item to the input list of the task.
      description: |
        Creates a new entry in the given Task's input list. Given metadata
        is assigned to the new list item.
      tags:
        - Tasks
      parameters:
        - name: sid
          type: string
          in: path
          required: true
          description: ID of the Service managing the current Task
        - name: tid
          in: path
          type: string
          required: true
          description: ID of the current task.
        - name: href
          in: query
          type: string
          description: |
            URL of the document to add. This is a convenient way of
            adding a document without constructing a list item first.
        - name: item
          in: body
          description: |
            Complete list item metadata for the new task input list item.
            Use EITHER doc OR item parameter; if both are present, item is used.
          schema:
            $ref: '#/definitions/ListItem'
      responses:
        200:
          description: OK, task input list item created, item data returned.
          schema:
            $ref: '#/definitions/ListItem'
        401:
          description: Unauthorized (Auth token invalid)
          schema:
            $ref: '#/definitions/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          schema:
            $ref: '#/definitions/Error'
        404:
          description: Not found
          schema:
            $ref: '#/definitions/Error'
        409:
          description: |
            Conflict, resource could not be updated. See error message for
            details.
          schema:
            $ref: '#/definitions/Error'
        500:
          description: Application Error
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - oauth:
          - authN
# ==============================================================================
  /services/{sid}/tasks/{tid}/input/{id}:
    get:
      summary: Retrieve task item details
      description: |
        FIXME
      tags:
        - Tasks
      parameters:
        - name: sid
          type: string
          in: path
          required: true
          description: ID of the Service managing the current Task
        - name: tid
          in: path
          type: string
          required: true
          description: ID of the current task.
        - name: id
          in: path
          type: string
          required: true
          description: ID of the input list item
      responses:
        200:
          description: OK, input list item data returned.
          schema:
            $ref: '#/definitions/ListItem'
        401:
          description: Unauthorized (Auth token invalid)
          schema:
            $ref: '#/definitions/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          schema:
            $ref: '#/definitions/Error'
        404:
          description: Not found
          schema:
            $ref: '#/definitions/Error'
        500:
          description: Application Error
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - oauth:
          - authN
# ------------------------------------------------------------------------------
    put:
      summary: Update the current task input list item (complete, replace)
      description: |
        Replaces the task input list item's metadata, including the document
        reference.
      tags:
        - Tasks
      parameters:
        - name: sid
          type: string
          in: path
          required: true
          description: ID of the Service managing the current Task
        - name: tid
          in: path
          type: string
          required: true
          description: ID of the current task.
        - name: id
          in: path
          type: string
          required: true
          description: ID of the input list item
        - name: item
          in: body
          description: |
            complete item metadata for the task item.
          schema:
            $ref: '#/definitions/ListItem'
      responses:
        200:
          description: OK, list item updated. Item data returned.
          schema:
            $ref: '#/definitions/ListItem'
        401:
          description: Unauthorized (Auth token invalid)
          schema:
            $ref: '#/definitions/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          schema:
            $ref: '#/definitions/Error'
        404:
          description: Not found
          schema:
            $ref: '#/definitions/Error'
        409:
          description: |
            Conflict, resource could not be updated. See error message for
            details.
          schema:
            $ref: '#/definitions/Error'
        500:
          description: Application Error
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - oauth:
          - authN
# ------------------------------------------------------------------------------
    patch:
      summary: Update a task input list item (partial, merge)
      description: |
        Updates task input list item metadata, replacing present entries and
        adding missing ones. No metadata is deleted by the patch.
      tags:
        - Tasks
      parameters:
        - name: sid
          type: string
          in: path
          required: true
          description: ID of the Service managing the current Task
        - name: tid
          in: path
          type: string
          required: true
          description: ID of the current task.
        - name: id
          in: path
          type: string
          required: true
          description: ID of the task input list item to update
        - name: item
          in: body
          schema:
            $ref: '#/definitions/ListItem'
          description: |
            (Partial) metadata of an input list item.
      responses:
        200:
          description: OK, task input list item updated. Item data returned.
          schema:
            $ref: '#/definitions/ListItem'
        401:
          description: Unauthorized (Auth token invalid)
          schema:
            $ref: '#/definitions/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          schema:
            $ref: '#/definitions/Error'
        404:
          description: Not found
          schema:
            $ref: '#/definitions/Error'
        409:
          description: |
            Conflict, resource could not be updated. See error message for
            details.
          schema:
            $ref: '#/definitions/Error'
        500:
          description: Application Error
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - oauth:
          - authN
# ------------------------------------------------------------------------------
    delete:
      summary: Delete a task input list item
      description: |
        Deletes an item from a Task's input list. The deleted ID is
        permanently orphaned, other list items keep their IDs.
      tags:
        - Tasks
      parameters:
        - name: sid
          type: string
          in: path
          required: true
          description: ID of the Service managing the current Task
        - name: tid
          in: path
          type: string
          required: true
          description: ID of the current task.
        - name: id
          in: path
          type: string
          required: true
          description: ID of the input list item to delete
      responses:
        204:
          description: OK, input list item deleted.
        401:
          description: Unauthorized (Auth token invalid)
          schema:
            $ref: '#/definitions/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          schema:
            $ref: '#/definitions/Error'
        404:
          description: Not found
          schema:
            $ref: '#/definitions/Error'
        409:
          description: |
            Conflict, resource could not be deleted. See error message for
            details.
          schema:
            $ref: '#/definitions/Error'
        500:
          description: Application Error
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - oauth:
          - authN
# ==============================================================================
  /services/{sid}/tasks/{tid}/output:
    get:
      summary: Retrieve list of task output items
      description: |
        This route provides access to a Task's list of output documents. Output
        lists of Tasks are structure-wise identical with Lists in general,
        they differ in that they are Task-internal and hence not available via
        the /lists route. Output lists can have list-level metadata, and each
        list item can have metadata as well.
        A call to this route will provide the list-level metadata and an
        inventory of the collection. Access output list items via the 'items'
        sub-collection. Use the 'embed' parameter to include item metadata
        in the result.
      tags:
        - Tasks
      parameters:
        - name: sid
          type: string
          in: path
          required: true
          description: ID of the Service managing the current Task
        - name: tid
          in: path
          type: string
          required: true
          description: ID of the current task.
        - name: embed
          type: string
          in: query
          description: |
            Use 'embed' to include sub-collection metadata in the result.
            - "items": Include list-item metadata.
      responses:
        200:
          description: OK, collection of output list items returned
          schema:
            $ref: '#/definitions/List'
        401:
          description: Unauthorized (Auth token invalid)
          schema:
            $ref: '#/definitions/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          schema:
            $ref: '#/definitions/Error'
        404:
          description: Not found
          schema:
            $ref: '#/definitions/Error'
        500:
          description: Application Error
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - oauth:
          - authN
# ==============================================================================
  /services/{sid}/tasks/{tid}/output/{id}:
    get:
      summary: Retrieve task output list item details
      description: |
        This route provides access to individual task output items.
      tags:
        - Tasks
      parameters:
        - name: sid
          type: string
          in: path
          required: true
          description: ID of the Service managing the current Task
        - name: tid
          in: path
          type: string
          required: true
          description: ID of the current task.
        - name: id
          in: path
          type: string
          required: true
          description: ID of the output list item
      responses:
        200:
          description: OK, output list item data returned.
          schema:
            $ref: '#/definitions/ListItem'
        401:
          description: Unauthorized (Auth token invalid)
          schema:
            $ref: '#/definitions/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          schema:
            $ref: '#/definitions/Error'
        404:
          description: Not found
          schema:
            $ref: '#/definitions/Error'
        500:
          description: Application Error
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - oauth:
          - authN

# ==============================================================================
# LISTS
# ==============================================================================
  /lists:
    get:
      summary: Get collection of available Lists.
      description: |
        This is the list of Lists of the authenticated user. Use metadata property
        names and regular expressions in URL query string to search for entries
        and the offset and limit parameters to control the number of results returned.
      tags:
        - Lists
      parameters:
        - name: offset
          type: integer
          in: query
          default: 0
          description: Index of first result to return.
        - name: limit
          type: integer
          in: query
          default: 50
          description: Number of results to return. Maximum is 500.
        - name: sort
          type: string
          in: query
          description: |
            Sort query results. Comma separated list of property names, prefixed with '-'
            for descending sort order. Example: 'sort=date,-name'
        - name: embed
          type: string
          in: query
          description: |
            Include information about collection members.
            - "items": Include item data
            - "permissions": User access rights on each List
            - "metadata": Return list of lists metadata. Example:
              ```
              {
                exportTypes: [{
                  name: 'csv',
                  description: 'Export a CSV file',
                  mimeType: 'text/csv'
                }],
                importTypes: [{
                  name: 'csv',
                  description: 'Import a CSV file',
                  mimeType: 'text/csv'
                }]
              }
              ```
      responses:
        200:
          description: OK, collection of lists is returned.
          schema:
            type: array
            items:
              $ref: '#/definitions/List'
        401:
          description: Unauthorized (Auth token invalid)
          schema:
            $ref: '#/definitions/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          schema:
            $ref: '#/definitions/Error'
        404:
          description: No lists available
          schema:
            $ref: '#/definitions/Error'
        500:
          description: Application Error
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - oauth:
          - authN
# ------------------------------------------------------------------------------
    post:
      summary: Create new List
      description: |
        Creates a new entry in the list of Lists. The `Content-Type` HTTP header
        defines the format of the import data. Default is JSON. If a URL is
        given in query as parameter `href` the list to import is retrieved from that URL.
      tags:
        - Lists
      parameters:
        - name: List
          in: body
          required: true
          description: metadata of the document list to create.
          schema:
            $ref: '#/definitions/List'
        - name: href
          in: query
          type: string
          description: |
            URL of the list to add. Example: `http://somehost:3456/path/to/mylist.csv`
      responses:
        200:
          description: OK, list created. List metadata returned.
          schema:
            $ref: '#/definitions/List'
        401:
          description: Unauthorized (Auth token invalid)
          schema:
            $ref: '#/definitions/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          schema:
            $ref: '#/definitions/Error'
        409:
          description: |
            Conflict, resource could not be created. See error message for
            details.
          schema:
            $ref: '#/definitions/Error'
        500:
          description: Application Error
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - oauth:
          - authN
# ==============================================================================
  /lists/{lid}:
    get:
      summary: Retrieve metadata for the current List.
      description: |
        This is the root record for a given list. It contains List-level
        metadata. Use the 'embed' parameter to include information about
        sub-ressource like items or access rights.
        The client controls the exported data format with the `Accept` HTTP header
        field. Default is JSON.
      tags:
        - Lists
      parameters:
        - name: lid
          in: path
          type: string
          required: true
          description: ID of the current list.
        - name: embed
          type: string
          in: query
          description: |
            Include information about collection members or sub-ressources.
            - "items": Include item data
            - "permissions": Include user access rights for the current user.
      responses:
        200:
          description: OK, metadata is returned.
          schema:
            $ref: '#/definitions/List'
        401:
          description: Unauthorized (Auth token invalid)
          schema:
            $ref: '#/definitions/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          schema:
            $ref: '#/definitions/Error'
        404:
          description: Not found
          schema:
            $ref: '#/definitions/Error'
        500:
          description: Application Error
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - oauth:
          - authN
# ------------------------------------------------------------------------------
    put:
      summary: Update List metadata (complete, replace)
      description: |
        This will completely replace the existing List metadata (if any) by the
        given metadata. Note that only List metadata itself can be updated.
        Internal auto-generated metadata (links; embedded), if present,
        are ignored.
      tags:
        - Lists
      parameters:
        - name: lid
          in: path
          type: string
          required: true
          description: ID of the current list.
        - name: update
          in: body
          description: |
            New Metadata for the list
          schema:
            $ref: '#/definitions/List'
      responses:
        200:
          description: OK, document list updated. New metadata returned.
          schema:
            $ref: '#/definitions/List'
        401:
          description: Unauthorized (Auth token invalid)
          schema:
            $ref: '#/definitions/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          schema:
            $ref: '#/definitions/Error'
        404:
          description: Not found
          schema:
            $ref: '#/definitions/Error'
        409:
          description: |
            Conflict, resource could not be updated. See error message for
            details.
          schema:
            $ref: '#/definitions/Error'
        500:
          description: Application Error
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - oauth:
          - authN
# ------------------------------------------------------------------------------
    patch:
      summary: Update List metadata (partial, merge)
      description: |
        Updates or adds part of the List metadata. Only given metadata
        will be replaced or added, no metadata will be removed. Note that
        only List metadata can be updated; internal auto-generated metadata
        (links, embedded), if present, are ignored.
      tags:
        - Lists
      parameters:
        - name: lid
          in: path
          type: string
          required: true
          description: ID of the current list.
        - name: update
          in: body
          description: |
            New Metadata for the list
          schema:
            $ref: '#/definitions/List'
      responses:
        200:
          description: OK, document list updated. New metadata returned.
          schema:
            $ref: '#/definitions/List'
        401:
          description: Unauthorized (Auth token invalid)
          schema:
            $ref: '#/definitions/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          schema:
            $ref: '#/definitions/Error'
        404:
          description: Not found
          schema:
            $ref: '#/definitions/Error'
        409:
          description: |
            Conflict, resource could not be updated. See error message for
            details.
          schema:
            $ref: '#/definitions/Error'
        500:
          description: Application Error
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - oauth:
          - authN
# ------------------------------------------------------------------------------
    delete:
      summary: Delete the current list
      description: |
        Deletes the current list inclusive all it's items, but not the documents.
      tags:
        - Lists
      parameters:
        - name: lid
          in: path
          type: string
          required: true
          description: ID of the current list.
      responses:
        204:
          description: OK, list removed.
        401:
          description: Unauthorized (Auth token invalid)
          schema:
            $ref: '#/definitions/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          schema:
            $ref: '#/definitions/Error'
        404:
          description: Not found
          schema:
            $ref: '#/definitions/Error'
        500:
          description: Application Error
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - oauth:
          - authN
# ==============================================================================
  /lists/{lid}/items:
    get:
      summary: Get List items.
      description: |
        This is the collection of items currently in the List. For performance
        reasons, only references are returned by default.
        Use metadata property names and regular expressions in URL query string
        to search for entries and the offset and limit parameters to control
        the number of results returned.
      tags:
        - Lists
      parameters:
        - name: lid
          in: path
          type: string
          required: true
          description: ID of the current list.
        - name: offset
          type: integer
          in: query
          default: 0
          description: Index of first result to return.
        - name: limit
          type: integer
          in: query
          default: 50
          description: Number of results to return. Maximum is 500.
        - name: sort
          type: string
          in: query
          description: |
            Sort query results. Comma separated list of property names, prefixed with '-'
            for descending sort order. Example: 'sort=href,-index'
        - name: embed
          type: string
          in: query
          description: |
            Sub-ressources to include in the response.
            - "items": Include metadata for each List
            - "permissions": Include user access rights
      responses:
        200:
          description: OK, collection of list items is returned.
          schema:
            type: array
            items:
              $ref: '#/definitions/ListItem'
        401:
          description: Unauthorized (Auth token invalid)
          schema:
            $ref: '#/definitions/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          schema:
            $ref: '#/definitions/Error'
        404:
          description: Not found
          schema:
            $ref: '#/definitions/Error'
        500:
          description: Application Error
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - oauth:
          - authN
# ------------------------------------------------------------------------------
    post:
      summary: Appended and item to the list.
      description: |
        Lists are are ordered sets, items have consecutive indices (0..n).
        Posting this route will append a new item to the List.
      tags:
        - Lists
      parameters:
        - name: lid
          in: path
          type: string
          required: true
          description: ID of the current list.
        - name: href
          in: query
          type: string
          description: |
            Relative URL of the document instance to add to the list
        - name: item
          in: body
          schema:
            $ref: '#/definitions/ListItem'
          description: |
            Use EITHER href OR item. If both are present, item is used.
      responses:
        200:
          description: OK, document reference has been added to the list.
          schema:
            $ref: '#/definitions/ListItem'
        401:
          description: Unauthorized (Auth token invalid)
          schema:
            $ref: '#/definitions/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          schema:
            $ref: '#/definitions/Error'
        404:
          description: Not found
          schema:
            $ref: '#/definitions/Error'
        409:
          description: |
            Conflict, resource could not be created. See error message for
            details.
          schema:
            $ref: '#/definitions/Error'
        500:
          description: Application Error
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - oauth:
          - authN
# ==============================================================================
  /lists/{lid}/items/{id}:
    get:
      summary: Retrieve item data of the current list element
      description: |
        Get metadata record of a list item. Note that the 'id' is NOT the
        index, which is part of item metadata.
      tags:
        - Lists
      parameters:
        - name: lid
          in: path
          type: string
          required: true
          description: ID of the current list.
        - name: id
          in: path
          type: string
          required: true
          description: ID of the current element.
      responses:
        200:
          description: OK, List item data is returned
          schema:
            $ref: '#/definitions/ListItem'
        401:
          description: Unauthorized (Auth token invalid)
          schema:
            $ref: '#/definitions/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          schema:
            $ref: '#/definitions/Error'
        404:
          description: Not found
          schema:
            $ref: '#/definitions/Error'
        500:
          description: Application Error
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - oauth:
          - authN
# ------------------------------------------------------------------------------
    put:
      summary: Update current list item (complete, replace)
      description: |
        Update and replace the entire metadata record of the current list item.
        Note that the ID is NOT the index of the item in the List. The index
        is part of item metadata.
      tags:
        - Lists
      parameters:
        - name: lid
          in: path
          type: string
          required: true
          description: ID of the current list.
        - name: id
          in: path
          type: string
          required: true
          description: ID of the current element.
        - name: item
          in: body
          required: true
          schema:
            $ref: '#/definitions/ListItem'
          description: |
            New item data to replace existing entry
      responses:
        200:
          description: OK, List item is updated, item data returned
          schema:
            $ref: '#/definitions/ListItem'
        401:
          description: Unauthorized (Auth token invalid)
          schema:
            $ref: '#/definitions/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          schema:
            $ref: '#/definitions/Error'
        404:
          description: Not found
          schema:
            $ref: '#/definitions/Error'
        409:
          description: |
            Conflict, resource could not be updated. See error message for
            details.
          schema:
            $ref: '#/definitions/Error'
        500:
          description: Application Error
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - oauth:
          - authN
# ------------------------------------------------------------------------------
    patch:
      summary: Update current list item (partial, merge)
      description: |
        Update the metadata record of the current list item, adding missing
        entries but removing nothing. Note that the ID is NOT the index of the
        item in the list. The index is part of item metadata.
      tags:
        - Lists
      parameters:
        - name: lid
          in: path
          type: string
          required: true
          description: ID of the current list.
        - name: id
          in: path
          type: string
          required: true
          description: ID of the current element.
        - name: href
          in: query
          type: string
          description: |
            Relative URL of document to link. This is a convenient way
            of just updating the href property of the existing List item.
        - name: item
          in: body
          schema:
            $ref: '#/definitions/ListItem'
          description: |
            New link data to replace existing entry. Use EITHER item OR
            href; if both are present, item is used.
      responses:
        200:
          description: OK, List item is updated, item data returned
          schema:
            $ref: '#/definitions/ListItem'
        401:
          description: Unauthorized (Auth token invalid)
          schema:
            $ref: '#/definitions/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          schema:
            $ref: '#/definitions/Error'
        404:
          description: Not found
          schema:
            $ref: '#/definitions/Error'
        409:
          description: |
            Conflict, resource could not be updated. See error message for
            details.
          schema:
            $ref: '#/definitions/Error'
        500:
          description: Application Error
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - oauth:
          - authN
# ------------------------------------------------------------------------------
    delete:
      summary: Remove the current element from the list
      description: |
        Deletes an entry from a list. Only the list entry is removed, not
        the document. Note that id is NOT the index of an item in the List.
        The index is part of item metadata.
      tags:
        - Lists
      parameters:
        - name: lid
          in: path
          type: string
          required: true
          description: ID of the current list.
        - name: id
          in: path
          type: string
          required: true
          description: ID of the current element.
      responses:
        204:
          description: OK, list element removed.
        401:
          description: Unauthorized (Auth token invalid)
          schema:
            $ref: '#/definitions/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          schema:
            $ref: '#/definitions/Error'
        404:
          description: Not found
          schema:
            $ref: '#/definitions/Error'
        500:
          description: Application Error
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - oauth:
          - authN

# ==============================================================================
# PANELS
# ==============================================================================
  /ui:
    get:
      summary: Retrieve list of default UI panels available to the user.
      description: |
        The SEAL Operator user interface provides the user with a set of
        default panels to use. A GET call to this route returns a list of panels
        available to the current user. Default panels cannot be edited or deleted.
      tags:
        - Panels
      responses:
        200:
          description: OK, list of UI panel configurations returned.
          schema:
            type: array
            items:
              $ref: '#/definitions/PanelItem'
        401:
          description: Unauthorized (Auth token invalid)
          schema:
            $ref: '#/definitions/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          schema:
            $ref: '#/definitions/Error'
        500:
          description: Application Error
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - oauth:
          - authN
# ----------------------------------------------------------------------------
  /ui/{pid}:
    get:
      summary: Retrieve the default configuration of a UI panel.
      description: |
        A GET call to this route returns a JSON object containing the default configuration
        of the panel.
      tags:
        - Panels
      parameters:
        - name: pid
          in: path
          type: string
          required: true
      responses:
        200:
          description: OK, panel configuration is returned.
          schema:
            $ref: '#/definitions/ConfigItem'
        401:
          description: Unauthorized (Auth token invalid)
          schema:
            $ref: '#/definitions/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          schema:
            $ref: '#/definitions/Error'
        500:
          description: Application Error
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - oauth:
          - authN
# ----------------------------------------------------------------------------
  /panels:
    get:
      summary: Retrieve list of UI panels available to the user.
      description: |
        The SEAL Operator user interface provides the user with a set of
        panels to use. A GET call to this route returns a list of user defined
        panels available to the current user. User-defined configurations can
        be stored using a POST request; these can also be edited and deleted later.
      tags:
        - Panels
      responses:
        200:
          description: OK, list of UI panel configurations returned.
          schema:
            type: array
            items:
              $ref: '#/definitions/ConfigItem'
        401:
          description: Unauthorized (Auth token invalid)
          schema:
            $ref: '#/definitions/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          schema:
            $ref: '#/definitions/Error'
        500:
          description: Application Error
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - oauth:
          - authN
# ----------------------------------------------------------------------------
    post:
      summary: Save a (user-specific) panel configuration.
      description: |
        Users can save panel configurations they intend to (re-)use in later
        sessions under a name.
        If the ConfigItem does not contain a "name" key, a name for the
        configuration will be auto-generated.
      tags:
        - Panels
      parameters:
        - name: configuration
          in: body
          schema:
            $ref: '#/definitions/ConfigItem'
          required: true
          description: |
            ConfigItem containing the configuration to store.
      responses:
        200:
          description: |
            OK, configuration was saved. The returned configItem contains
            the generated ID.
          schema:
            $ref: '#/definitions/ConfigItem'
        401:
          description: Unauthorized (Auth token invalid)
          schema:
            $ref: '#/definitions/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          schema:
            $ref: '#/definitions/Error'
        409:
          description: |
            Conflict. A panel configuration under the "name" given in the
            ConfigItem already exists.
        500:
          description: Application Error
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - oauth:
          - authN
  # ----------------------------------------------------------------------------
  /panels/{pid}:
    get:
      summary: Retrieve a specific panel configuration
      description: |
        Returns a ConfigItem containing configuration for a stored panel.
      tags:
        - Panels
      parameters:
        - name: pid
          type: string
          in: path
          required: true
          description: ID of the panel
      responses:
        200:
          description: OK, configuration returned.
          schema:
            $ref: '#/definitions/ConfigItem'
        401:
          description: Unauthorized (Auth token invalid)
          schema:
            $ref: '#/definitions/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          schema:
            $ref: '#/definitions/Error'
        404:
          description: Not found. The given pid is unknown.
          schema:
            $ref: '#/definitions/Error'
        500:
          description: Application Error
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - oauth:
          - authN
  # ----------------------------------------------------------------------------
    put:
      summary: Updates a saved panel configuration
      description: |
        A PUT request to a panel configuration will replace the entire stored
        configuration with the one contained in the request body.
        It's possible to use a different value for the "name" key in order
        to rename the saved configuration; however, the new name must not be
        in use. Note that only user-defined panel configurations can be updated.
      tags:
        - Panels
      parameters:
        - name: pid
          type: string
          in: path
          required: true
          description: ID of the panel
        - name: configuration
          in: body
          schema:
            $ref: '#/definitions/ConfigItem'
          required: true
          description: |
            ConfigItem containing the configuration to store.
      responses:
        200:
          description: OK, configuration updated.
          schema:
            $ref: '#/definitions/ConfigItem'
        401:
          description: Unauthorized (Auth token invalid)
          schema:
            $ref: '#/definitions/Error'
        403:
          description: |
            Forbidden. The current user lacks access rights, or is trying to
            update a read-only default configuration.
            schema:
              $ref: '#/definitions/Error'
        409:
          description: |
            Conflict. A panel configuration under the "name" given in the
            ConfigItem already exists.
        500:
          description: Application Error
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - oauth:
          - authN
  # ----------------------------------------------------------------------------
    delete:
      summary: Delete a stored panel configuration
      description: |
        User-defined panel configurations can be delete by a DELETE request to
        this route.
      tags:
        - Panels
      parameters:
        - name: pid
          type: string
          in: path
          required: true
          description: ID of the panel configuration to remove.
      responses:
        200:
          description: OK, panel configuration was deleted, return deleted configuration.
          schema:
            $ref: '#/definitions/ConfigItem'
        401:
          description: Unauthorized (Auth token invalid)
          schema:
            $ref: '#/definitions/Error'
        403:
          description: |
            Forbidden. The current user lacks access rights, or is trying to
            delete a read-only default configuration.
            schema:
              $ref: '#/definitions/Error'
        500:
          description: Application Error
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - oauth:
          - authN

# ==============================================================================
# Configuration
# ==============================================================================
  /config:
    # Note: slightly misusing the OpenAPI spec juju here, since those
    # guys won't support optional path segments. Which, alas, are absolutely
    # required here if we don't want to write lots of code to map between
    # Consul and OpenAPI.
    get:
      summary: Access a configuration item or path
      description: |
        Use this route to browse the configuration.
        Configuration is structured unix file-system like, in a path/to/item way.
        Use path/to/item as 'path' parameter to access a specific item or together
        with 'keys' parameter for retrieving only keys.
      tags:
        - Configuration
      parameters:
        - name: path
          type: string
          in: query
          description: Path/to/config/item
        - name: keys
          in: query
          type: boolean
          allowEmptyValue: true
          description: |
            Return an array of strings containing all recursively fetched
            keys below the given 'path'. Without or an empty 'path' all
            available keys are returned.

             **Example response:**
            ```
            [
            "key1",
            "path/to/key2",
            "some/other/path/to/key3"
            ]
            ```
      responses:
        200:
          description: OK, configuration items returned.
          schema:
            allOf:
            # FIXME: Should be oneOf! OneOf is not supported in OpenAPI 2.0,
            # but will be in OpenAPI 3.0. Using bleeping edge here...
              - type: array
                items:
                  type: string
                  description: Valid configuration key
              - type: object
                items:
                  $ref: '#/definitions/ConfigItem'
        401:
          description: Unauthorized (Auth token invalid)
          schema:
            $ref: '#/definitions/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          schema:
            $ref: '#/definitions/Error'
        404:
          description: The given ConfigItem was not found.
          schema:
            $ref: '#/definitions/Error'
        500:
          description: Application Error
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
    put:
      summary: Store a configuration item
      description: |
        Stores the ConfigItem in the request body at the given path.
      tags:
        - Configuration
      parameters:
        - name: path
          type: string
          in: query
          description: Path/to/config/item
        - name: configuration
          in: body
          required: true
          schema:
            $ref: '#/definitions/ConfigItem'
      responses:
        200:
          description: OK, configuration stored.
          schema:
            $ref: '#/definitions/ConfigItem'
        401:
          description: Unauthorized (Auth token invalid)
          schema:
            $ref: '#/definitions/Error'
        403:
          description: |
            Forbidden. User lacks access rights to change configuration.
            schema:
              $ref: '#/definitions/Error'
        500:
          description: Application Error
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
    delete:
      summary: Delete a configuration item
      description: |
        Deletes a single ConfigItem at the given path or all ConfigItems in the whole tree below if
        path does not point to an actual item.
      tags:
        - Configuration
      parameters:
        - name: path
          type: string
          in: query
          required: true
          description: Path/to/config/item
      responses:
        200:
          description: OK, configuration deleted.
          schema:
            $ref: '#/definitions/ConfigItem'
        401:
          description: Unauthorized (Auth token invalid)
          schema:
            $ref: '#/definitions/Error'
        403:
          description: |
            Forbidden. User lacks access rights to change configuration.
            schema:
              $ref: '#/definitions/Error'
        500:
          description: Application Error
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'

# ==============================================================================
# Messages
# ==============================================================================
  /messages:
    get:
      summary: Access the users messages
      description: |
        Every user has his own list of messages containing info, warning and error messages of various panels and actions.
        The messages are stored on server until they expire. This route provides access to the messages.
        Use property names and regular expressions in URL query string to search for
        entries and the offset and limit parameters to control the number of results returned.
      tags:
        - Messages
      parameters:
        - name: offset
          type: integer
          in: query
          default: 0
          description: Index of first result to return.
        - name: limit
          type: integer
          in: query
          default: 25
          description: Number of results to return. Maximum is 500.
        - name: sort
          type: string
          in: query
          description: |
            Sort query results. Comma separated list of property names, prefixed with '-'
            for descending sort order. Example: 'sort=date,-type'
      responses:
        200:
          description: OK, list of entries is returned.
          schema:
            type: array
            items:
              $ref: '#/definitions/Message'
        401:
          description: Unauthorized (Auth token invalid)
          schema:
            $ref: '#/definitions/Error'
        404:
          description: The service does not provide messages
          schema:
            $ref: '#/definitions/Error'
        500:
          description: Application Error
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - oauth:
          - authN
# ------------------------------------------------------------------------------
    post:
      summary: Create new message entry.
      description: |
        Creates a new record in the message list and assigns the posted data.
        The server adds a uuid and a creation date to each entry if not already present.
      tags:
        - Messages
      parameters:
        - name: message
          in: body
          required: true
          description: metadata of the entry to be created
          schema:
            $ref: '#/definitions/PostMessage'
      responses:
        200:
          description: OK, entry created. Entry metadata returned.
          schema:
            $ref: '#/definitions/Message'
        401:
          description: Unauthorized (Auth token invalid)
          schema:
            $ref: '#/definitions/Error'
        404:
          description: The service does not provide messages
          schema:
            $ref: '#/definitions/Error'
        409:
          description: |
            Conflict, ressource could not be created. See error message for
            details.
          schema:
            $ref: '#/definitions/Error'
        500:
          description: Application Error
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - oauth:
          - authN
# ------------------------------------------------------------------------------
  /messages/{uuid}:
    patch:
      summary: Update a message entry.
      description: |
        Update a message entry. Only data given with the patch will be
         changed/added; no entries removed. Updating uuid and creation date is prohibited.
      tags:
        - Messages
      parameters:
        - name: uuid
          in: path
          type: string
          required: true
          description: ID of the message entry
        - name: message
          in: body
          required: true
          description: metadata of the entry to be created
          schema:
            $ref: '#/definitions/Message'
      responses:
        200:
          description: OK, message entry updated, new message returned.
          schema:
            $ref: '#/definitions/Message'
        401:
          description: Unauthorized (Auth token invalid)
          schema:
            $ref: '#/definitions/Error'
        404:
          description: The service does not provide messages
          schema:
            $ref: '#/definitions/Error'
        409:
          description: |
            Conflict, ressource could not be created. See error message for
            details.
          schema:
            $ref: '#/definitions/Error'
        500:
          description: Application Error
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - oauth:
          - authN

# ==============================================================================
# Functions
# ==============================================================================
  /services/{sid}/function:
    get:
      summary: List connector specific functions
      description: |
        For panels static configuration data is sometimes not sufficient,
        dynamically retrieved data from the backend system is needed. The
        function routes allows the connector to make dynamic data and functionality
        available to the client.
        The function routes are synchronous calls in contrary to the asynchronous commands.
        This route returns all supported functions.
      tags:
        - Functions
      parameters:
        - name: sid
          type: string
          in: path
          required: true
          description: ID of the current repository.
      responses:
        200:
          description: OK, list of entries is returned.
          schema:
            $ref: '#/definitions/Functions'
        401:
          description: Unauthorized (Auth token invalid)
          schema:
            $ref: '#/definitions/Error'
        404:
          description: The service does not provide functions
          schema:
            $ref: '#/definitions/Error'
        500:
          description: Application Error
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - oauth:
          - authN
# ------------------------------------------------------------------------------
  /services/{sid}/function/{fid}:
    post:
      summary: Access a connector specific function
      description: |
        This route triggers a connector specific function and returns the result.
        The function routes are synchronous calls in contrary to the asynchronous commands.
      tags:
        - Functions
      parameters:
        - name: sid
          type: string
          in: path
          required: true
          description: ID of the current repository.
        - name: fid
          type: string
          in: path
          required: true
          description: Name of the function to calls
        - name: params
          type: string
          in: query
          description: |
            String with a list of function specific parameter as key value pairs. Syntax:
            ```
            params="key::value[;key::value]*"
            ```
      responses:
        200:
          description: OK, function result is returned.
        401:
          description: Unauthorized (Auth token invalid)
          schema:
            $ref: '#/definitions/Error'
        404:
          description: The service does not provide this function
          schema:
            $ref: '#/definitions/Error'
        500:
          description: Application Error
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - oauth:
          - authN

# ==============================================================================
# SESSIONS
# ==============================================================================
  /sessions:
    get:
      summary: Get session information
      description: |
        Get number of currently established sessions of user
      tags:
        - Sessions
      responses:
        200:
          description: OK, return object with session information
          schema:
            $ref: '#/definitions/SessionInfo'
        401:
          description: Unauthorized (Auth token invalid)
          schema:
            $ref: '#/definitions/Error'
        403:
          description: |
            Forbidden. The user lacks acces rights to access the service list.
          schema:
            $ref: '#/definitions/Error'
        500:
          description: Application Error
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      security:
        - oauth:
          - authN

################################################################################
# Data Types
################################################################################
definitions:
  SessionInfo:
    type: object
    description: Informations about users sessions
    properties:
      no:
        type: integer
        description: number of currently open sessions of this user
  Service:
    type: object
    description: |
      A Service represents a target system connected to the SEAL Operator
      framework. It may be able to process tasks and/or provide access to
      documents, under its /tasks and /repo routes.
    properties:
      id:
        type: string
        description: Identifier of the Service within the SEAL Operator
      name:
        type: string
        description: Label describing the Service
      metadata:
        type: object
        description: Metadata of the Service
      links:
        type: object
        description: |
          If requested by MIME type, the links section contains hrefs to
          - "self": The Service itself
          - "permissions": User permissions on the Service
      embedded:
        type: object
        description: |
          Sub-collections and/or sub-ressources requested through the embed
          query parameter.

  BaseRepoEntry:
    type: object
    description: |
      A RepoEntry contains user defined metadata with any number of arbitrary
      properties and two mandatory properties 'name' and 'type'.
    properties:
      name:
        type: string
        description: (File) name of the Entry
      type:
        type: string
        enum:
          - document
          - collection
        description: Type of RepoEntry.
      metadata:
        type: object
        description: Metadata assigned to the entry

  RepoEntry:
    type: object
    description: |
      A RepoEntry represents a record within the Repository part of a Service.
      A RepoEntry may be either a document or a collection. All RepoEntries
      may contain metadata and user permission records. collections may also
      contain children, while documents may have binary content.
    properties:
      id:
        type: string
        description: Local ID of the document within the repository.
      uuid:
        type: string
        description: Global ID of the document, created by SEAL Operator
      name:
        type: string
        description: (File) name of the Entry
      type:
        type: string
        enum:
          - document
          - collection
        description: Type of RepoEntry.
      links:
        type: object
        description: |
          If requested by MIME type, the links section contains hrefs to
          - "self": the document itself
          - "parent": the collection containing the document
          - "permissions": an object describing user permissions on the document
      embedded:
        type: object
        description: |
          Embedded sub-ressources as requested through the "embed" query
          parameter, e.g. "permissions", "icon", "thumb".
      metadata:
        type: object
        description: Metadata assigned to the entry

  List:
    type: object
    description: |
      A List is an ordered sequence of documents as list items. Each List can
      contain arbitrary metadata. List items may also have metadata assigned,
      which does not replace but complement document metadata. A document may
      not be unique within a List, i.e. a List can contain several items all
      pointing to the same document (but most likely with different item
      metadata).
    properties:
      uuid:
        type: string
        description: Unique identifier of the list, generated by SEAL Operator.
      name:
        type: string
        description: User defined name for the list. Doesn't have to be unique.
      created:
        type: integer
        format: date-time
        description: Timestamp of list creation
      lastModified:
        type: integer
        format: date-time
        description: Timestamp of list creation
      listLength:
        type: integer
        description: Number of items in list
      links:
        type: object
        description: |
          If requested by MIME type, the links section contains hrefs to
          - "self": the List itself
      embedded:
        type: object
        description: |
          Embedded sub-ressources or sub-collections, as requested throught the
          "embed" query parameter
        properties:
          listItems:
            type: array
            items:
              $ref: '#/definitions/ListItem'
      metadata:
        type: object
        description: List metadata. Note that these do not contain item metadata.

  ListItem:
    type: object
    properties:
      index:
        type: integer
        description: |
          This is the index of an item in a List. The index is maintained
          by the SEAL Operator backend. Setting the index to a value beyond
          the end of the list will move the item to the end of the list.
          Setting the index to 0 will move th item to the top of the list.
          Setting the index to a value in use by another item will replace
          this item, moving it (and all with higher indices) one space down
          in the list, by increasing their index values.
      href:
        type: string
        description: URL location of linked ressource
      metadata:
        type: object
        description: Additional data to be stored with the link

  StatusType:
    type: string
    description: Definition of allowed status names
    enum:
      - open
      - processing
      - completed
      - paused
      - aborted
      - failed

  TaskMetadata:
    type: object
    description: |
      A task metadata object contains user defined metadata with any number of arbitrary
      properties and the optional property 'name'.
    properties:
      name:
        type: string
        description: Name of the Task
      metadata:
        type: object
        description: Metadata assigned to the task

  Task:
    type: object
    properties:
      name:
        type: string
      sid:
        type: string
      tid:
        type: string
      metadata:
        type: object
        description: Task metadata. Note that these do not contain item metadata.
      created:
        type: integer
        format: date-time
        description: Timestamp of task creation
      started:
        type: integer
        format: date-time
        description: Timestamp of task started
      finished:
        type: integer
        format: date-time
        description: Timestamp of task finished
      inputListLength:
        type: integer
        description: Number of items in input list
      outputListLength:
        type: integer
        description: Number of items in output list
      status:
        $ref: '#/definitions/StatusType'
      links:
        type: object
        description: |
          If requested, the links section contains hrefs to
          - "self": the Task itself
          - "input": input documents
          - "output": output documents
      embedded:
        type: object
        description: |
          Embedded sub-ressources or sub-collections, as requested throught the
          "embed" query parameter

  ConfigItem:
    description: |
      A JSON object containing key-value pairs representing the configuration.
    type: object

  PanelItem:
    description: A JSON object containing name and id of a PanelListItem
    type: object
    properties:
      pid:
        type: string
        description: unique id of the PanelListItem
      name:
        type: string
      type:
        type: string
        description: the panel type the configuration is for, e.g. scratch, p4,...


  Error:
    type: object
    properties:
      code:
        type: integer
        format: int32
      message:
        type: string
      metadata:
        type: object

  Action:
    description: |
      A JSON object containing the name of the command to execute and it's paramters.
    type: object
    properties:
      action:
        type: string
        enum:
          - start
          - abort
          - pause
          - resume

  Command:
    description: |
      A JSON object containing the name of the command to execute and it's paramters.
    type: object
    properties:
      action:
        type: string
        enum:
          - copy
          - move
      parameter:
        description: |
          Command specific parameter, e.g. href's of documents
        type: object

  CommandStatus:
    description: A JSON object containing a command and it's current status
    type: object
    properties:
      cid:
        type: string
      status:
        $ref: '#/definitions/StatusType'
      command:
        $ref: '#/definitions/Command'


  PostMessage:
    description: |
      A JSON object containing a message
    type: object
    properties:
      type:
        type: string
        description: The message type
        enum:
          - info
          - warning
          - error
      text:
        type: string
        description: The message text
      source:
        type: string
        description: Name of the panel which created the message

  Message:
    description: |
      A JSON object containing a message
    type: object
    properties:
      uuid:
        type: string
        description: A server side defined uuid for each new entry
      type:
        type: string
        description: The message type
        enum:
          - info
          - warning
          - error
      text:
        type: string
        description: The message text
      date:
        type: integer
        format: int64
        description: The creation time of the message as timestamp
      source:
        type: string
        description: Name of the panel which created the message
      read:
        type: boolean
        description: Flag if the message has already been read by user

  Functions:
    description: |
      Contains for each available function one object with an href to the function.
      Key of each object is the function name.
    type: object
