openapi: '3.0.2'
info:
  title: DPF Management REST API
  version: '1.0'

tags:
  - name: jobs
    description: Job Management APIs
  - name: version
    description: Version Information

servers:
  - url: http://localhost:4304/rest/dpf/v1

paths:
  /jobs:
    get:
      tags:
        - jobs

      summary: get all jobIds
      description:
        Returns a list of all jobIds currently held in storage backend.
        The result of this query can be reduced by filters provided in query parameters.
        If no filters are provided, all available jobIds are returned.

      parameters:
        - name: limit
          in: query
          description:
            Maximum number of jobId's per page.
            If parameter 'limit' is not provided, the response will use it's default limit value to limit items per page.
          required: false
          schema:
            type: integer
            example: 100
        - name: offset
          in: query
          description:
            Start index of the requested page.
            If no offset is provided, index at position '0' is assumed, meaning the first page is returned.
          required: false
          schema:
            type: integer
            example: 150
        - name: sort
          in: query
          description:
            The sort argument is a comma separated list of fields to sort the results by. If the sort field is prefixed with a minus sign (-), the results will be sorted in descending order, otherwise in ascending order.
          required: false
          schema:
            type: string
            example: 'sort=wf,-timestamp.tsInserted'
        - name: total
          in: query
          description:
            The total argument spezifies if the total number of jobIds should be returned. Default of total is `true``.
          required: false
          schema:
            type: boolean
            example: 'total=false'
        - name: .*
          in: query
          description:
            Any other query parameter will be treated as a filter. The filter parameter is a key-value pair where the key is an arbitrary field in the job object to filter by and the value is the value to filter for. Standard comparison operations (=, !=, >, <, >=, <=) are supported. All given filters are combined with a logical AND.
          required: false
          schema:
            type: string
            pattern: .*
            example: 'wf=example&current.exitStatus!=OK'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
                    example: 23
                    description: total number of jobIds found matching this query
                  limit:
                    type: integer
                    example: 10
                    default: 50
                    description: number of jobIds in this response's page
                  offset:
                    type: integer
                    example: 20
                    description: offset within total number of jobIds where this page starts from
                  jobIds:
                    type: array
                    items:
                      type: string
                      example:
                        - '2024041909203198765'
                        - '2024041909213198766'
                        - '2024041909223198767'
                    description: list of jobIds in current page (with regards to offset and limit)

  /jobs/{jobId}:
    get:
      tags:
        - jobs
      summary: get job details
      description:
        Returns a single job including details and history data according
        to the JSON schema defined in ADR 0001.
      parameters:
        - name: jobId
          in: path
          description: a DPF job's jobID
          required: true
          schema:
            $ref: '#/components/schemas/jobId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
        '404':
          description: No job for jobId found
    delete:
      tags:
        - jobs
      summary: delete jobs
      description:
        Marks the job identified by parameter jobId
        for deletion in backend.
      parameters:
        - name: jobId
          in: path
          description: a DPF job's jobID
          required: true
          schema:
            $ref: '#/components/schemas/jobId'
      responses:
        '204':
          description: OK (no content in response)
        '404':
          description: No job for jobId found
    put:
      tags:
        - jobs
      summary: modify jobs
      description:
        Modifies a job and returns the resulting job details. For now only the current status of a job can be changed.
        When the job's state is changed to `cancel`, of course the job is cancelled.
        When a job's state is set to repeat, the service will change the job's state to
        `repeat`, clean up the job's directory and afterwards set it's state to `transferred`
        again, so the job will be processed once more.
      parameters:
        - name: jobId
          in: path
          description: a DPF job's jobID
          required: true
          schema:
            $ref: '#/components/schemas/jobId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              example:
                current:
                  status: repeat
              properties:
                current:
                  type: object
                  properties:
                    status:
                      type: string
                      enum:
                        - repeat
                        - cancel
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Job"
        '400':
          description: parameters in body are not applicable
        '404':
          description: No job for jobId found

  /version:
    get:
      tags:
        - version
      summary: get version information
      description: Returns this service's version information
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Version'

components:
  schemas:
    Job:
      type: object
      properties:
        _id:
          type: string
          example: '3fb45606-dd85-434b-b349-cd5c124824d0'
        jobId:
          $ref: '#/components/schemas/jobId'
        jobName:
          type: string
          example: 'Vom Client vergebener Name'
        timestamps:
          type: object
          properties:
            tsInserted:
              type: number
            tsChanged:
              type: number
            tsFinished:
              type: number
        wf:
          type: string
        jobPriority:
          type: number
        current:
          type: object
          properties:
            status:
              type: string
            wfPosition:
              type: string
            wfPath:
              type: string
            wuInstanceId:
              type: string
            exitStatus:
              type: string
            jobState:
              type: string
            parameter:
              $ref: '#/components/schemas/ParameterList'
        history:
          type: array
          items:
            type: object
            properties:
              wfPosition:
                type: string
              wfPath:
                type: string
              exitStatus:
                type: string
              status:
                type: string
              jobState:
                type: string
              timestamp:
                type: string
              wuInstanceId:
                type: string
              parameter:
                $ref: '#/components/schemas/ParameterList'
              paramerterUsed:
                $ref: '#/components/schemas/ParameterList'
              parameterModified:
                $ref: '#/components/schemas/ParameterList'
            required:
              - wfPosition
              - wfPath
              - exitStatus
              - status
              - jobState
              - parameter
              - timestamp
              - wuInstanceId
              - paramerterUsed
              - parameterModified

    Version:
      type: object
      properties:
        swaggerApiVersion:
          type: string
          example: '1.0'
        serviceName:
          type: string
          example: 'dpf-management-rest-api'
        serviceVersion:
          type: string
          example: '1.6.3'
    jobId:
      type: string
      example: '2024041909203198765'

    Parameter:
      type: object
      properties:
        key:
          type: string
        value:
          type: string

    ParameterList:
      type: object
      additionalProperties:
        $ref: '#/components/schemas/Parameter'
