openapi: 3.0.3

info:
  title: UTBMS Codes
  description: "This endpoint provides functionality for the management of UTBMS codes. For information of how to construct requests utilising fieldsets, sorting, paging, filters, and '*includes*', please refer to the API Developer Portal. E&OE."
  version: "1.0"

externalDocs:
  description: API Developer Portal - Constructing API Requests
  url: https://docs.actionstep.com/api-requests/

paths:
  '/utbmscodes':
    get:
      description: Returns the collection of all UTBMS codes.
      tags:
        - UTBMS Codes
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedUTBMSCodes'

    post:
      description: Create a new UTBMS code.
      tags:
        - UTBMS Codes
      requestBody:
        $ref: '#/components/requestBodies/CreateUTBMSCode'
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UTBMSCode'

  '/utbmscodes/{id}':
    get:
      description: Returns a single UTBMS code.
      tags:
        - UTBMS Codes
      parameters:
        - name: id
          in: path
          description: Unique identifier for a single UTBMS code.
          required: true
          schema:
            type: string
            format: string
          example: A100
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UTBMSCode'

    put:
      description: Updates a single UTBMS code.
      tags:
        - UTBMS Codes
      parameters:
        - name: id
          in: path
          description: Unique identifier for a single UTBMS code.
          required: true
          schema:
            type: string
            format: string
          example: A100
      requestBody:
        $ref: '#/components/requestBodies/UpdateUTBMSCode'
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UTBMSCode'

    delete:
      description: Deletes a single UTBMS code.
      tags:
        - UTBMS Codes
      parameters:
        - name: id
          in: path
          description: Unique identifier for a single UTBMS code.
          required: true
          schema:
            type: string
            format: string
          example: A100
      responses:
        '204':
          description: Success, No Content.

components:
  schemas:
    PagedUTBMSCodes:
      type: object
      properties:
        UTBMSCodes:
          type: array
          items:
            $ref: '#/components/schemas/UTBMSCode'
        meta:
          $ref: '#/components/schemas/PageMetaData'

    PageMetaData:
      type: object
      properties:
        paging:
          $ref: '#/components/schemas/PagingData'

    PagingData:
      type: object
      properties:
        UTBMSCodes:
          $ref: '#/components/schemas/UTBMSCodesPageData'

    UTBMSCodesPageData:
      type: object
      properties:
        recordCount:
          description: The total number of UTBMS code records returned by the underlying query.
          type: integer
          example: 2487
        pageCount:
          description: The total number of pages generated by the underlying query.
          type: integer
          example: 50
        page:
          description: The page number for this page of UTBMS codes.
          type: integer
          example: 2
        pageSize:
          description: Page size.
          type: integer
          example: 50
        prevPage:
          description: A URL to the previous page of UTBMS codes.
          type: string
          example: https://ap-southeast-2.actionstep.com/api/rest/utbmscodes?page=1
        nextPage:
          description: A URL to the next page of UTBMS codes.
          type: string
          example: https://ap-southeast-2.actionstep.com/api/rest/utbmscodes?page=3

    UTBMSCode:
      type: object
      properties:
        id:
          description: Unique identifier (code) for the UTBMS code. 
          type: string
          format: string
          example: A100
          readOnly: true
        categoryCode:
          description: The category code to which the UTBMS code is associated.
          type: string
          format: string
          example: Activity codes
        parentUtbmsCode:
          description: The parent UTBMS code to which this UTBMS code is associated.
          type: string
          format: string
          example: AA10
        description:
          description: A description for the UTBMS code.
          type: string
          format: string
          example: Research
        overrideDescription:
          description: A custom description for the time entry description field. Only relevant for Activity codes.
          type: string
          format: string
          example: Case history research.
        enabled:
          description: Indicates if the UTBMS code is enabled for use. 
          type: string
          enum:
            - T
            - F
          default: T
          format: string
          example: T

    CreateUTBMSCode:
      type: object
      required:
        - utbmsCode
        - categoryCode
        - description
        - enabled
      properties:
        utbmsCode:
          description: Unique identifier (code) for the UTBMS code. 
          type: string
          format: string
          example: A100
        categoryCode:
          description: The category code to which the UTBMS code is associated.
          type: string
          format: string
          example: Activity codes
        parentUtbmsCode:
          description: The parent UTBMS code to which this UTBMS code is associated.
          type: string
          format: string
          example: AA10
        description:
          description: A description for the UTBMS code.
          type: string
          format: string
          example: Research
        overrideDescription:
          description: A custom description for the time entry description field. Only relevant for Activity codes.
          type: string
          format: string
          example: Case history research.
        enabled:
          description: Indicates if the UTBMS code is enabled for use. 
          type: string
          enum:
            - T
            - F
          default: T
          format: string
          example: T

    UpdateUTBMSCode:
      type: object
      properties:
        categoryCode:
          description: The category code to which the UTBMS code is associated.
          type: string
          format: string
          example: Activity codes
        parentUtbmsCode:
          description: The parent UTBMS code to which this UTBMS code is associated.
          type: string
          format: string
          example: AA10
        description:
          description: A description for the UTBMS code.
          type: string
          format: string
          example: Research
        overrideDescription:
          description: A custom description for the time entry description field. Only relevant for Activity codes.
          type: string
          format: string
          example: Case history research.
        enabled:
          description: Indicates if the UTBMS code is enabled for use. 
          type: string
          enum:
            - T
            - F
          default: T
          format: string
          example: T

  requestBodies:
    CreateUTBMSCode:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CreateUTBMSCode'

    UpdateUTBMSCode:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UpdateUTBMSCode'