openapi: 3.0.0
info:
  title: Listeditor API - ValueStreamer
  version: 3.0.0
  description: "This is the specification of the list editor REST API for data exchange with third-party systems."
servers:
  - url: https://api-tenant.valuestreamer.de/api

security:
  - basicAuth: [ ]
tags:
  - name: "List entries"
    description: "These endpoints can be used to create, update, or delete list entries."
  - name: "Meta data"
    description: "These endpoints can be used to query the required metadata of a list."

paths:
  /exchange/list/{list-id}/{team-id}:
    get:
      tags:
        - "List entries"
      summary: "Returns the list entries of a list in a given team, ordered by creation date (createdOn) desc."
      parameters:
        - in: "path"
          name: "list-id"
          description: "UUID of the list."
          required: true
          schema:
            type: "string"
            format: "uuid"
        - in: "path"
          name: "team-id"
          description: "UUID of the team."
          required: true
          schema:
            type: "string"
            format: "uuid"
        - in: "query"
          name: "page"
          description: "page id"
          required: false
          schema:
            type: "integer"
        - in: "query"
          name: "include"
          required: false
          schema:
            type: "string"
            enum: [ RESPONSIBLE, CASCADED, ALL ]
            default: RESPONSIBLE
          description: "Defines, which entries are included in the response:<ul>
                    <li><b>RESPONSIBLE</b>: Only include entries that the team is responsible for</li>
                    <li><b>CASCADED</b>: Only include entries that were cascaded by the team (i.e. entries that were created in the requested team, but have a different responsibleTeam)</li>
                    <li><b>ALL</b>: Include both, RESPONSIBLE + CASCADED entries</li></ul>"
      responses:
        '200':
          description: OK
          content:
            application/vs.v3.0+json:
              schema:
                allOf:
                  - properties:
                      page:
                        $ref: '#/components/schemas/Page'
                      entries:
                        type: array
                        items:
                          $ref: '#/components/schemas/ListData'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '500':
          $ref: '#/components/responses/InternalServerError'
    put:
      tags:
        - "List entries"
      summary: "Creates or updates list entries of a list in a given team."
      description: "The endpoint follows the approach that the complete PUT transaction for all entries is aborted and rolled back in case of a single validation error."
      parameters:
        - in: "path"
          name: "list-id"
          description: "UUID of the list."
          required: true
          schema:
            type: "string"
            format: "uuid"
        - in: "path"
          name: "team-id"
          description: "UUID of the list."
          required: true
          schema:
            type: "string"
            format: "uuid"
      requestBody:
        required: true
        content:
          application/vs.v3.0+json:
            schema:
              type: array
              items:
                allOf:
                  - $ref: '#/components/schemas/ListData'
      responses:
        '200':
          description: OK
          content:
            application/vs.v3.0+json:
              schema:
                type: array
                items:
                  allOf:
                    - $ref: '#/components/schemas/ListData'
        '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'
    post:
      tags:
        - "List entries"
      summary: "Creates a new entry."
      description: "This endpoint creates or updates a new entry."
      parameters:
        - in: "path"
          name: "list-id"
          description: "UUID of the list."
          required: true
          schema:
            type: "string"
            format: "uuid"
      requestBody:
        required: true
        content:
          application/vs.v3.0+json:
            schema:
              allOf:
                - $ref: '#/components/schemas/ListData'
              properties:
                dataId:
                  readOnly: true
      responses:
        '200':
          description: OK
          content:
            application/vs.v3.0+json:
              schema:
                $ref: '#/components/schemas/ListData'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /exchange/list/{list-id}/{team-id}/{entry-id}:
    get:
      tags:
        - "List entries"
      summary: "Returns a specific list entry by its id."
      parameters:
        - in: "path"
          name: "list-id"
          description: "UUID of the list."
          required: true
          schema:
            type: "string"
            format: "uuid"
        - in: "path"
          name: "entry-id"
          description: "ID of the entry."
          required: true
          schema:
            type: "string"
      responses:
        '200':
          description: OK
          content:
            application/vs.v3.0+json:
              schema:
                $ref: '#/components/schemas/ListData'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '500':
          $ref: '#/components/responses/InternalServerError'
    put:
      tags:
        - "List entries"
      summary: "Create or update an entry with a specific id."
      description: ""
      parameters:
        - in: "path"
          name: "list-id"
          description: "UUID of the list."
          required: true
          schema:
            type: "string"
            format: "uuid"
        - in: "path"
          name: "team-id"
          description: "UUID of the team."
          required: true
          schema:
            type: "string"
            format: "uuid"
        - in: "path"
          name: "entry-id"
          description: "ID of the entry."
          required: true
          schema:
            type: "string"
      requestBody:
        required: true
        content:
          application/vs.v3.0+json:
            schema:
              allOf:
                - $ref: '#/components/schemas/ListData'
              properties:
                dataId:
                  readOnly: true
      responses:
        '200':
          description: OK
          content:
            application/vs.v3.0+json:
              schema:
                $ref: '#/components/schemas/ListData'
        '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:
        - "List entries"
      summary: "Delete a specific entry by its id."
      parameters:
        - in: "path"
          name: "list-id"
          description: "UUID of the list."
          required: true
          schema:
            type: "string"
            format: "uuid"
        - in: "path"
          name: "team-id"
          description: "UUID of the team."
          required: true
          schema:
            type: "string"
            format: "uuid"
        - in: "path"
          name: "entry-id"
          description: "ID of the entry."
          required: true
          schema:
            type: "string"
      responses:
        '204':
          description: entry deleted
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /exchange/list/{list-id}/{team-id}/{entry-id}/status-history:
    get:
      tags:
        - "List entries"
      summary: "Get a entry's status history."
      parameters:
        - in: "path"
          name: "list-id"
          description: "UUID of the list."
          required: true
          schema:
            type: "string"
            format: "uuid"
        - in: "path"
          name: "team-id"
          description: "UUID of the team."
          required: true
          schema:
            type: "string"
            format: "uuid"
        - in: "path"
          name: "entry-id"
          description: "ID of the entry."
          required: true
          schema:
            type: "string"
      responses:
        '200':
          description: OK
          content:
            application/vs.v3.0+json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/History'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /exchange/list/meta:
    get:
      tags:
        - "Meta data"
      summary: "Returns the list of tenant-specific lists."
      responses:
        '200':
          description: OK
          content:
            application/vs.v3.0+json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                      format: uuid
                    title:
                      type: string
                      description: ""
                    active:
                      type: boolean
                    cascading:
                      type: boolean
                      description: "is cascading enabled for the list?"
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /exchange/list/meta/{list-id}:
    get:
      tags:
        - "Meta data"
      summary: "Returns the details of a list by its UUID."
      parameters:
        - in: "path"
          name: "list-id"
          description: "UUID of the List."
          required: true
          schema:
            type: "string"
      responses:
        '200':
          description: OK
          content:
            application/vs.v3.0+json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                  title:
                    type: string
                  active:
                    type: boolean
                    default: true
                  nameOfListEntry:
                    type: string
                  orderItems1:
                    type: string
                    format: uuid
                  orderItems2:
                    type: string
                    format: uuid
                  orderItems3:
                    type: string
                    format: uuid
                  cascading:
                    type: boolean
                    description: "Is cascading enabled for the list?"
                  fields:
                    type: array
                    items: {
                      anyOf: [
                        { $ref: '#/components/schemas/MetaFieldTextfield' },
                        { $ref: '#/components/schemas/MetaFieldSingleSelection' },
                        { $ref: '#/components/schemas/MetaFieldSingleSelectionFixed' },
                        { $ref: '#/components/schemas/MetaFieldMultiSelection' },
                        { $ref: '#/components/schemas/MetaFieldInteger' },
                        { $ref: '#/components/schemas/MetaFieldDecimal' },
                        { $ref: '#/components/schemas/MetaFieldDate' },
                        { $ref: '#/components/schemas/MetaFieldDateTime' },
                        { $ref: '#/components/schemas/MetaFieldCurrency' },
                        { $ref: '#/components/schemas/MetaFieldCheckbox' },
                        { $ref: '#/components/schemas/MetaFieldPriority' },
                        { $ref: '#/components/schemas/MetaFieldTeam' },
                        { $ref: '#/components/schemas/MetaFieldUser' }
                      ]
                    }
                  entryingTeams:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: uuid
                        name:
                          type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
  schemas:
    MetaFieldBase:
      type: object
      properties:
        key:
          type: string
          description: "This field contains the key name in the listdata JSON."
          example: "datan"
        type:
          type: string
          enum: [ TEXTFIELD, SINGLESELECTION, SINGLESELECTIONFIX, MULTISELECTION,
                  INTEGER, DECIMAL, DATE, DATETIME, CURRENCY, CHECKBOX, PRIORITY, TEAM,
                  USER, STATUS ]
        name:
          type: string
          description: "This field contains the name of the field in the user interface."
          example: ""
        mandatory:
          type: boolean
          default: false
          example: true
        orderId:
          type: number
          description: "Order of the fields (asc) in the user interface."
    MetaFieldTextfield:
      description: "This field is of type textfield and accepts characters and numbers."
      allOf:
        - $ref: '#/components/schemas/MetaFieldBase'
        - type: object
          properties:
            key:
              example: "data(n)"
            name:
              example: "E.g. Machine name"
            type:
              example: "TEXTFIELD"
            maxLength:
              type: number
              example: 50
              nullable: true
    MetaFieldSingleSelection:
      description: "This field is of type single selection and accepts the ID of the selected field option."
      allOf:
        - $ref: '#/components/schemas/MetaFieldBase'
        - type: object
          properties:
            key:
              example: "data(n)"
            name:
              example: "Selection field name"
            type:
              example: SINGLESELECTION
            options:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                  name:
                    type: string
                  orderId:
                    type: number
    MetaFieldSingleSelectionFixed:
      description: "This field is of type single selection (fixed values) and accepts the ID of the selected field option."
      allOf:
        - $ref: '#/components/schemas/MetaFieldBase'
        - type: object
          properties:
            key:
              example: "data(n)"
            name:
              example: ""
            type:
              example: SINGLESELECTIONFIXED
            options:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                  name:
                    type: string
                  orderId:
                    type: number
    MetaFieldMultiSelection:
      description: "This field is of type multi selection and accepts an array of the selected field value UUIDs."
      allOf:
        - $ref: '#/components/schemas/MetaFieldBase'
        - type: object
          properties:
            key:
              example: "data(n)"
            name:
              example: ""
            type:
              example: MULTISELECTION
            options:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                  name:
                    type: string
                  orderId:
                    type: number
    MetaFieldInteger:
      description: "This field is of type integer and accepts an integer value."
      allOf:
        - $ref: '#/components/schemas/MetaFieldBase'
        - type: object
          properties:
            key:
              example: "data(n)"
            name:
              example: ""
            type:
              example: INTEGER
    MetaFieldDecimal:
      description: "This field is of type decimal and accepts a decimal value."
      allOf:
        - $ref: '#/components/schemas/MetaFieldBase'
        - type: object
          properties:
            key:
              example: "data(n)"
            name:
              example: ""
            type:
              example: DECIMAL
    MetaFieldDate:
      description: "This field is of type date and accepts a date string as yyyy-MM-dd."
      allOf:
        - $ref: '#/components/schemas/MetaFieldBase'
        - type: object
          properties:
            key:
              example: "data(n)"
            name:
              example: "E.g. Goods receipt: 2099-05-05"
            type:
              example: DATE
    MetaFieldDateTime:
      description: "This field is of type date-time and accepts a date-time string according to RFC3339. E.g. yyyy-MM-ddThh:mm:ssZ / 2021-01-30T08:30:00Z"
      allOf:
        - $ref: '#/components/schemas/MetaFieldBase'
        - type: object
          properties:
            key:
              example: "data(n)"
            name:
              example: "E.g. 2021-01-30T08:30:00Z"
            type:
              example: DATETIME
    MetaFieldCurrency:
      description: "This field is of type currency and accepts an decimal value."
      allOf:
        - $ref: '#/components/schemas/MetaFieldBase'
        - type: object
          properties:
            key:
              example: "data(n)"
            name:
              example: "E.g. Turnover: EUR"
            type:
              example: CURRENCY
            currencyType:
              type: string
    MetaFieldCheckbox:
      description: "This field is of type boolean and accepts true/false."
      allOf:
        - $ref: '#/components/schemas/MetaFieldBase'
        - type: object
          properties:
            key:
              example: "data(n)"
            name:
              example: ""
            type:
              example: CHECKBOX
    MetaFieldPriority:
      description: "This field is of type priority and accepts a boolean true/false."
      allOf:
        - $ref: '#/components/schemas/MetaFieldBase'
        - type: object
          properties:
            key:
              example: "data_priority"
            name:
              example: ""
            type:
              example: PRIORITY
    MetaFieldTeam:
      description: "This field is of type team and accepts a team id (UUID)."
      allOf:
        - $ref: '#/components/schemas/MetaFieldBase'
        - type: object
          properties:
            key:
              example: "data_team"
            name:
              example: ""
            type:
              example: TEAM
    MetaFieldUser:
      description: "This field is of type user and accepts an user id (UUID)."
      allOf:
        - $ref: '#/components/schemas/MetaFieldBase'
        - type: object
          properties:
            key:
              example: "data_user"
            name:
              example: ""
            type:
              example: USER
    ListData:
      type: "object"
      properties:
        dataId:
          type: string
          description: "The identifier of the list entry for the given team and list. 
          If the field is empty when the entry is CREATED, ValueStreamer creates an unique UUID for you. Alternatively, you can insert your own id.
          Hint: If you insert your own id, make sure it only exists once for the given list."
          nullable: true
          minLength: 1
          maxLength: 36
        dataDone:
          type: boolean
          example: false
          description: "Defines whether the progress of the entry is active (done=FALSE) or closed (done=TRUE)."
        dataDescription:
          type: string
          description: "This field contains the input of the richtext description field."
          example: "Richtext description field"
          nullable: true
        dataPriority:
          type: boolean
          description: ""
        dataStatus:
          type: integer
          enum: [ 1,2,3 ]
          description: "1=green, 2=yellow, 3=red"
          example: 1
        dataStatusMessage:
          type: string
          description: "Includes the current status message."
          maxLength: 600
        dataUser:
          type: string
          format: "uuid"
        data1:
          type: string
          example: "Example: String text"
        data2:
          type: number
          example: 2000
        data3:
          type: boolean
        data4:
          type: string
          format: date
        data5:
          type: string
          format: date-time
        data6:
          type: string
          format: "uuid"
        data7:
          type: array
          description: "multiselection"
          items:
            type: string
            format: "uuid"
        data8:
          type: string
        data9:
          type: string
        data10:
          type: string
        data11:
          type: string
        data12:
          type: string
        data13:
          type: string
        data14:
          type: string
        data15:
          type: string
        data16:
          type: string
        data17:
          type: string
        data18:
          type: string
        data19:
          type: string
        data20:
          type: string
        data21:
          type: string
        data22:
          type: string
        data23:
          type: string
        data24:
          type: string
        data25:
          type: string
        data26:
          type: string
        data27:
          type: string
        data28:
          type: string
        data29:
          type: string
        data30:
          type: string
        responsibleTeam:
          type: string
          format: "uuid"
          description: "Contains the ID of the responsible team of the list entry"
          nullable: false
        dataTeam:
          type: string
          format: "uuid"
          description: "If the list has a team dropdown, contains the ID of the selected team"
          nullable: true
        createdByTeam:
          type: string
          format: uuid
          readOnly: false
          description: "ID of the team which created the entry"
        createdBy:
          type: string
          format: uuid
          readOnly: true
          description: "ID of the user which created the entry"
        createdOn:
          type: string
          format: date
          readOnly: true
        modifiedBy:
          type: string
          format: uuid
          readOnly: true
        modifiedOn:
          type: string
          format: date
          readOnly: true
        doneOn:
          type: string
          format: date
          readOnly: true
      required:
        - "dataId"
        - "responsibleTeam"
        - "dataDone"
        - "dataDescription"
        - "dataStatus"
        - "dataStatusMessage"
    History:
      type: object
      properties:
        status:
          type: integer
          enum: [ 1,2,3 ]
          description: "1 green, 2 yellow, 3 red"
        comment:
          type: string
          description: ''
          maxLength: 600
        modifiedBy:
          type: string
          format: 'uuid'
        modifiedOn:
          type: string
          format: date

    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"
    # Schema for error response body
    Error:
      type: object
      properties:
        errorId:
          type: string
          description: "Unique error ID for this error response"
        errorMessage:
          type: string
  responses:
    NotFound:
      description: Resource not found
      content:
        application/vs.v3.0+json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Not authorized
      content:
        application/vs.v3.0+json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Bad request
      content:
        application/vs.v3.0+json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalServerError:
      description: Internal server error
      content:
        application/vs.v3.0+json:
          schema:
            $ref: '#/components/schemas/Error'
    UnsupportedMediaType:
      description: UnsupportedMediaType
      content:
        application/vs.v3.0+json:
          schema:
            $ref: '#/components/schemas/Error'
    Conflict:
      description: Conflict
      content:
        application/vs.v3.0+json:
          schema:
            $ref: '#/components/schemas/Error'