openapi: 3.0.0
info:
  title: Task board API - ValueStreamer
  version: 1.0.2
  description: "This is the specification of the REST interface for the task board."
servers:
  - url: https://api-tenant.valuestreamer.de/api
security:
  - basicAuth: []
tags:
- name: "Task"
  description: ""
- name: "Task: Description"
  description: "Endpoints for fetching and updating the data of the richtext input field 'description'."
- name: "Task: Status history"
  description: "Endpoints for fetching the status history of a task."
- name: "Meta"
  description: "Endpoints to retrieve meta data for tasks."
paths:
  /exchange/tasks:
    get:
      tags:
        - "Task"
      summary: "Retrieve a collection of tasks."
      description: "Returns a list of tasks, ordered by creation date (desc). By default, all tasks except tasks with progress=ARCHIVED are returned."
      parameters:
        - in: "query"
          name: "team"
          description: "UUID of a team to fetch the tasks for."
          required: true
          schema:
            type: "string"
            format: "uuid"
        - in: "query"
          name: "progress"
          description: "Fetch only tasks with specific progress"
          explode: false
          allowEmptyValue: false
          schema:
            type: array
            items:
              $ref: '#/components/schemas/Progress'
        - in: "query"
          name: "include"
          description: "Defines, which tasks are included in the response:<ul>
          <li><b>RESPONSIBLE</b>: Only include tasks that the team is responsible for</li>
          <li><b>CASCADED</b>: Only include tasks, that were cascaded by the team (i.e. tasks that were created in requested team, but have different responsibleTeam)</li>
          <li><b>ALL</b>: Include both, RESPONSIBLE + CASCADED </li></ul>"
          required: true
          schema:
            type: string
            enum: [ALL, RESPONSIBLE, CASCADED]
            default: ALL
        - in: "query"
          name: "page"
          description: "page id"
          required: true
          schema:
            type: "integer"
            maximum: 50
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - properties:
                      page:
                        $ref: '#/components/schemas/Page'
                      entries:
                        type: array
                        items:
                          $ref: '#/components/schemas/TaskExcerpt'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      tags:
        - "Task"
      summary: "Create a task"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/TaskDetails'
                - properties:
                    creationTeam:
                      type: string
                      format: 'uuid'
                      description: "Optional. Can be used to create a cascaded task, by providing a specific creationTeam"
                      nullable: true
                      required: false
                - required:
                  - "category"
                  - "priority"
                  - "responsibleTeam"
                  - "status"
                  - "targetEndDate"
                  - "targetEffort"
                  - "title"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskDetails'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /exchange/tasks/{id}:
    get:
      tags:
        - "Task"
      summary: "Retrieve a specific task."
      parameters:
        - in: "path"
          name: "id"
          description: "UUID of the task."
          required: true
          schema:
            type: "string"
            format: "uuid"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/TaskDetails'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
    put:
      tags:
        - "Task"
      summary: "Update a task"
      parameters:
        - in: "path"
          name: "id"
          description: "UUID of the task."
          required: true
          schema:
            type: "string"
            format: "uuid"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/TaskDetails'
                - required:
                    - "category"
                    - "priority"
                    - "responsibleTeam"
                    - "status"
                    - "targetEndDate"
                    - "targetEffort"
                    - "title"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/TaskDetails'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      tags:
        - "Task"
      summary: "Delete a specific task."
      parameters:
        - in: "path"
          name: "id"
          description: "UUID of the task."
          required: true
          schema:
            type: "string"
            format: "uuid"
      responses:
        '204':
          description: "Record deleted"
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /exchange/tasks/{id}/description:
    summary: "Get the data of the richtext input field 'description' of the task."
    get:
      tags:
        - "Task: Description"
      summary: "Get the description."
      parameters:
        - in: "path"
          name: "id"
          description: "UUID of the task."
          required: true
          schema:
            type: "string"
            format: "uuid"
      responses:
        '200':
          description: OK
          content:
            text/html:
              schema:
                $ref: '#/components/schemas/Description'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
    put:
      tags:
        - "Task: Description"
      summary: "Update the description."
      parameters:
        - in: "path"
          name: "id"
          description: "UUID of the task."
          required: true
          schema:
            type: "string"
            format: "uuid"
      requestBody:
        required: true
        description: "Description of task as HTML string"
        content:
          text/html:
            schema:
              $ref: '#/components/schemas/Description'
      responses:
        '200':
          description: OK
          content:
            text/html:
              schema:
                $ref: '#/components/schemas/Description'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /exchange/tasks/{id}/status-history:
    get:
      tags:
        - "Task: Status history"
      summary: "Get the status history of the task, ordered by date (desc.)"
      parameters:
        - in: "path"
          name: "id"
          description: "UUID of the task."
          required: true
          schema:
            type: "string"
            format: "uuid"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: "array"
                items:
                  $ref: '#/components/schemas/History'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /exchange/taskboard-categories:
    get:
      tags:
        - "Meta"
      summary: "Get all available categories on the tenant"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Category'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /exchange/taskboard-labels:
    get:
      tags:
        - "Meta"
      summary: "Get all available labels on the tenant"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Label'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /exchange/teams/{id}/taskboard:
    get:
      tags:
        - "Meta"
      summary: "Get the details of a taskboard for a specific team: Available labels and categories"
      parameters:
        - in: "path"
          name: "id"
          description: "UUID of the team"
          required: true
          schema:
            type: "string"
            format: "uuid"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskboardDetails'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'   
components:
  securitySchemes:
    basicAuth:           
      type: http
      scheme: basic
  schemas:
    Category:
      description: 'A category must be assigned to a task.'
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: "UUID"
        name:
          type: array
          description: "name"
          items:
            type: object
            properties:
              language:
                $ref: '#/components/schemas/Languages'
              name:
                type: string
                description: "Translation"
        color:
          type: string
          description: "Color is used as a background color of a task in the task board."
          maxLength: 10
        colorStripes:
          type: string
          description: "Color that is used for the hatched background of a task in the task board."
        locked:
          type: boolean
        default:
          type: boolean
          description: "The category marked as default=true is available in every team/taskboard."
        global:
          type: boolean
        problemSolving:
          type: boolean
          description: "The category with problemSolving=true is for internal use only and cannot be used for creating/updating tasks."
    # Schema for error response body
    Error:
      description: "Common error response object returned if a request failed."
      type: object
      properties:
        errorId:
          type: string
          description: "Unique error ID for this error response"
        errorMessage:
          type: string
    Description:
      type: string
      maxLength: 4294967295
      description: 'Description shown in the richtext editor of a task as HTML string.'
      example: "<p>Description of <b>Task A</b>.</p>"
    History:
      description: "For each change of the status of a task, a new history object will be created documenting the reason for the status change and the previous status."
      type: object
      properties:
        comment:
          type: string
          description: "Comment/reason for the status update."
        modifiedByUser:
          type: string
          format: 'uuid'
        modifiedDate:
          type: string
          format: date
        status:
          $ref: '#/components/schemas/Status'
    Label:
      description: "Label of a task. The label is displayed on the task in the Taskboard."
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: "UUID of the label"
        name:
          type: array
          description: "name"
          items: 
            type: object
            properties:
              language:
                $ref: '#/components/schemas/Languages'
              name:
                type: string
                description: "Translation"
        removable:
          type: boolean
        tCard:
          type: boolean
          description: "The label with tCard=true is for internal use only and cannot be used for creating/updating tasks."
    Languages:
      type: string
      enum: [DE,EN]
    Page:
      type: object
      readOnly: true
      properties:
        page:
          type: integer
          description: "Number of the current page"
        elementsOnPage:
          type: integer
          description: "Number of elements on the current page"
        elementsPerPage:
          type: integer
          description: "Number of elements per page"
        totalPages:
          type: integer
          description: "Number of all pages"
        totalElements:
          type: integer
          description: "Number of all elements"
    Progress:
      description: "Progress of a task. Determines in which column a task is shown in the Taskboard. ARCHIVED is read-only and cannot be set via PUT or POST."
      type: string
      enum:
        - CREATED
        - PLANNED
        - INPROGRESS
        - DONE
        - ARCHIVED
    Status:
      description: "Status of a task. 1=green, 2=blue, 3=red."
      type: string
      enum: [1,2,3]
      nullable: false
    TaskExcerpt:
      type: "object"
      properties:
        id:
          type: string
          format: uuid
          description: "UUID of the task."
          readOnly: true
        title:
          type: string
          description: "Title of the task"
        category:
          type: string
          format: 'uuid'
          description: "UUID of the corresponding category"
        createdByTeam:
          type: string
          format: uuid
          description: "UUID of the team that created the task."
        label:
          type: string
          format: uuid
          nullable: true
          description: "UUID of the label. Can be null, e.g. for migrated T-Card tasks."
        progress:
          $ref: '#/components/schemas/Progress'
        priority:
          type: boolean
        responsiblePerson:
          type: string
          format: 'uuid'
          description: "UUID of the user the task is assigned to."
        responsibleTeam:
          type: string
          format: 'uuid'
          description: "UUID of the team the task is assigned to."
        status:
          $ref: '#/components/schemas/Status'
        targetEndDate:
          type: string
          format: 'date'
          description: "Target end date of the task, e.g. 2021-01-15"
        targetEffort:
          type: number
          format: double
          description: "Estimated effort in hours for the task"
    TaskDetails:
      type: "object"
      properties:
        id:
          type: string
          format: uuid
          description: "UUID of the task."
          readOnly: true
        title:
          type: string
          description: "Title of the task"
          maxLength: 255
          nullable: false
        actualEndDate:
          type: string
          format: 'date'
          description: "Date when the task was finished, resp. progress was set to DONE."
          readOnly: true
        actualStartDate:
          type: string
          format: 'date'
          description: "Date when the task was started, resp. progress was set to INPROGRESS."
          readOnly: true
        actualEffort:
          type: number
          format: double
          description: "Actual effort in hours for the task"
        archivedDate:
          type: string
          format: 'date'
          description: "Archiving date of the task."
          readOnly: true
        category:
          type: string
          format: 'uuid'
          description: "UUID of the corresponding category"
          nullable: false
        createdBy:
          type: string
          format: 'uuid'
          description: "UUID of the user that created the task."
          readOnly: true
        createdByTeam:
          type: string
          format: 'uuid'
          description: "UUID of the creator team."
          readOnly: true
        createdDate:
          type: string
          format: 'date'
          description: "Creation date."
          readOnly: true
        label:
          type: string
          format: uuid
          nullable: true
          description: "UUID of the label. Can be null, e.g. for migrated T-Card tasks."
        linkedToTeam:
          type: string
          format: 'uuid'
          description: "UUID of the linked 'parent' team (i.e. team of the linked process activity)."
          readOnly: true
        linkedToProcessitem:
          type: string
          format: uuid
          description: "UUID of the linked process activity."
          readOnly: true
        linkedToProcess:
          type: string
          format: uuid
          description: "UUID of the linked process board."
          readOnly: true
        modifiedBy:
          type: string
          format: 'uuid'
          description: "UUID of the user who last modified the record."
          readOnly: true
        modifiedDate:
          type: string
          format: 'date'
          description: ""
          readOnly: true
        priority:
          type: boolean
          description: ""
          nullable: false
        progress:
          $ref: '#/components/schemas/Progress'
        responsiblePerson:
          type: string
          format: 'uuid'
          description: "UUID of the assigned user."
        responsibleTeam:
          type: string
          format: 'uuid'
          description: "UUID of the responsible team."
          nullable: false
        status:
          $ref: '#/components/schemas/Status'
        statusMessage:
          type: string
          description: "Must be provided if the status is changed."
        targetEndDate:
          type: string
          format: 'date'
          description: "Target end date of the task, e.g. 2021-01-15"
          nullable: false
        targetStartDate:
          type: string
          format: 'date'
          description: "Target start date of the task, e.g. 2021-01-15"
        targetEffort:
          type: number
          format: double
          description: "Estimated target effort in hours for the task"
          nullable: false
        tCard:
          type: boolean
          description: "True, if task is a recurring task (T-Card)"
          example: false
    TaskboardDetails:
      type: "object"
      properties:
        categories:
          type: array
          items:
            $ref: '#/components/schemas/Category'
        labels:
          type: array
          items:
            $ref: '#/components/schemas/Label'
  responses:
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Not authorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    UnsupportedMediaType:
      description: UnsupportedMediaType
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Conflict:
      description: Conflict
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'