openapi: 3.0.1
info:
  title: Asset management related APIs
  description: This is the specification of Open APIs to access the OT Companion Asset management data for building your own applications or integrations to IT tools 
  version: '1.0'
  contact:
    name: API Support
    email: feedback.otams.si@siemens.com
   
#servers:
#- url: https://qa.otams.siemens.cloud/
paths:

  "/api/v1/assets":
    get:
      tags:
        - assets
      summary: Get all assets
      description: Get all assets
      operationId: getAssets
      parameters:
        - name: extPageReq
          in: query
          description: Page request for fetching assets.
          required: true
          schema:
            "$ref": "#/components/schemas/ExtPageReq"
        - name: searchArray
          in: query
          description: Array of search strings for filtering assets.
          required: false
          schema:
            type: array
            items:
              type: string
        - name: stationId
          in: query
          description: station to search on id
          required: false
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/PageRsp"
        '400':
          description: Bad Request
        '500':
          description: Internal Server Error
    post:
      tags:
        - assets
      summary: Create an asset
      description: Create an asset
      operationId: createExtAsset
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ExtCreateAssetReq"
        required: true
      responses:
        '201':
          description: Asset created successfully
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/SuccessRsp"
        '404':
          description: Asset Type or Station Id not found
        '409':
          description: Asset name already exist
        '412':
          description: Mandatory parameter is missing
        '500':
          description: Internal Server Error

  "/api/v1/assets/{id}":
    get:
      tags:
      - assets
      summary: Get asset
      description: Get asset by id
      operationId: getExtAssetById
      parameters:
      - name: id
        in: path
        description: UUID of asset that needs to be fetched
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ExtAssetExt"
        '404':
          description: Asset Id not found
        '500':
          description: Internal Server Error
    delete:
      tags:
      - assets
      summary: Delete asset
      description: Delete asset by asset id
      operationId: deleteExtAsset
      parameters:
      - name: id
        in: path
        description: UUID of asset that needs to be deleted.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Asset deleted successfully
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/SuccessRsp"
        '404':
          description: Asset Id not found
        '500':
          description: Internal Server Error
    patch:
      tags:
      - assets
      summary: Update asset
      description: Update asset by asset id
      operationId: updateExtAsset
      parameters:
      - name: id
        in: path
        description: UUID of asset that needs to be updated.
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ExtUpdateAssetReq"
        required: true
      responses:
        '200':
          description: Asset Updated successfully
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/SuccessRsp"
        '404':
          description: Asset Id or Asset Type or Station Id not found
        '409':
          description: Asset name already exist
        '500':
          description: Internal Server Error

  "/api/v1/components":
    post:
      tags:
      - components
      summary: Create component
      description: Create component
      operationId: createComponent
      requestBody:
        content:
          application/json:
            schema:
              description: Request for component creation
              oneOf:
              - "$ref": "#/components/schemas/CreateHardwareComponentReq"
              - "$ref": "#/components/schemas/CreateSoftwareComponentReq"
        required: true
      responses:
        '201':
          description: Component created successfully
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/SuccessRsp"
        '400':
          description: Can't add component without parent or Can't add software-component as first component
        '404':
          description: Asset ID or Parent component ID or Product ID or Product variant ID not found
        '412':
          description: Mandatory field is missing
        '500':
          description: Internal Server Error

  "/api/v1/components/{id}":
    get:
      tags:
      - components
      summary: Get component
      description: Get component by id
      operationId: getComponent
      parameters:
      - name: id
        in: path
        description: UUID of asset that needs to be fetched.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ExtComponentExt"
        '404':
          description: Component Id not found
        '500':
          description: Internal Server Error
    delete:
      tags:
      - components
      summary: Delete component
      description: Delete component by component id
      operationId: deleteComponent
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/SuccessRsp"
        '404':
          description: Component Id not found
        '500':
          description: Internal Server Error
    patch:
      tags:
      - components
      summary: Update component
      description: Update component by component id
      operationId: updateComponent
      parameters:
      - name: id
        in: path
        description: UUID of component that needs to be updated.
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              description: Request for updating component
              oneOf:
              - "$ref": "#/components/schemas/UpdateHardwareComponentReq"
              - "$ref": "#/components/schemas/UpdateSoftwareComponentReq"
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/SuccessRsp"
        '404':
          description: Component Id or hardware id or hardware type or software id or software type not found
        '500':
          description: Internal Server Error

  "/api/v1/stations":
    get:
      tags:
      - stations
      summary: Get stations
      description: Get all stations
      operationId: getExtStations
      parameters:
      - name: page
        in: query
        description: Number of page that is fetched. Default value is zero.
        required: false
        schema:
          type: integer
          format: int32
          default: 0
      - name: pageSize
        in: query
        description: Size of page that is fetched. Default value is 20.
        required: false
        schema:
          type: integer
          format: int32
          default: 20
      - name: sortField
        in: query
        description: Sort field on which sorting to be performed.
        required: false
        schema:
          type: string
      - name: sortDirection
        in: query
        description: Sort direction for sorting.
        required: false
        schema:
          type: string
      - name: search
        in: query
        description: Search string that is to be filtered by.
        required: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/PageRsp"
        '500':
          description: Internal Server Error
    post:
      tags:
      - stations
      summary: Create station
      description: Create station
      operationId: createExtStation
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/CreateStationReq"
        required: true
      responses:
        '201':
          description: Station created successfully
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/SuccessRsp"
        '409':
          description: Location with name already exist
        '412':
          description: Mandatory field is missing
        '500':
          description: Internal Server Error

  "/api/v1/stations/{id}":
    get:
      tags:
      - stations
      summary: Get station
      description: Get station by id
      operationId: getExtStation
      parameters:
      - name: id
        in: path
        description: UUID of station that is fetched.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ExtStationExt"
        '404':
          description: Location Id not found
        '500':
          description: Internal Server Error
    delete:
      tags:
      - stations
      summary: Delete station
      description: Delete station by id
      operationId: deleteExtStation
      parameters:
      - name: id
        in: path
        description: UUID of station that needs to be deleted.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/DeleteBulkRsp"
        '404':
          description: Location Id not found
        '500':
          description: Internal Server Error
    patch:
      tags:
      - stations
      summary: Update station
      description: Update station by id
      operationId: updateExtStation
      parameters:
      - name: id
        in: path
        description: UUID of station that needs to updated
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/UpdateStationReq"
        required: true
      responses:
        '200':
          description: Station updated successfully
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/SuccessRsp"
        '404':
          description: Location Id not found
        '500':
          description: Internal Server Error


components:
  schemas:
    ExtPageReq:
      type: object
      properties:
        page:
          type: integer
          format: int32
        pageSize:
          type: integer
          format: int32
        search:
          type: string
        sortField:
          type: string
        sortDirection:
          type: string
          enum:
            - ASC
            - DESC
    CreateTagReq:
      required:
        - value
      type: object
      properties:
        value:
          maxLength: 255
          minLength: 1
          type: string
        id:
          type: string
    ExtCreateAssetReq:
      required:
        - assetName
        - assetTypeId
      type: object
      properties:
        assetName:
          maxLength: 255
          minLength: 1
          type: string
        assetId:
          maxLength: 128
          minLength: 0
          type: string
        assetTypeId:
          type: string
        commissioningDate:
          type: string
          format: date-time
        operationalState:
          type: string
          enum:
            - ACTIVE
            - STANDBY
            - NOT_IN_SERVICE
            - NONE
        processCriticality:
          type: string
          enum:
            - HIGH
            - LOW
        tags:
          type: array
          items:
            "$ref": "#/components/schemas/CreateTagReq"
        description:
          maxLength: 5000
          minLength: 0
          type: string
        stationId:
          type: string
      description: Request for asset creation.
    TagReqExt:
      type: object
      properties:
        value:
          type: string
        id:
          type: string
    ExtUpdateAssetReq:
      type: object
      properties:
        assetName:
          maxLength: 255
          minLength: 1
          type: string
        assetId:
          maxLength: 128
          minLength: 0
          type: string
        assetTypeId:
          type: string
        commissioningDate:
          type: string
          format: date-time
        modifiedDate:
          type: string
          format: date-time
        operationalState:
          type: string
          enum:
            - ACTIVE
            - STANDBY
            - NOT_IN_SERVICE
            - NONE
        processCriticality:
          type: string
          enum:
            - HIGH
            - LOW
        description:
          maxLength: 5000
          minLength: 0
          type: string
        stationId:
          type: string
        tags:
          type: array
          items:
            "$ref": "#/components/schemas/TagReqExt"
      description: Request for updating asset
    CreateComponentReq:
      required:
        - assetId
        - componentName
        - componentType
      type: object
      properties:
        assetId:
          type: string
        componentType:
          type: string
          enum:
            - SOFTWARE
            - HARDWARE
        parentComponentId:
          maxLength: 128
          minLength: 1
          type: string
        componentName:
          maxLength: 255
          minLength: 1
          type: string
        componentDescription:
          maxLength: 1024
          minLength: 1
          type: string
        componentId:
          maxLength: 128
          minLength: 0
          type: string
        sapOrderNumber:
          maxLength: 64
          minLength: 1
          type: string
        productId:
          type: string
        additionalComponentInformation:
          type: string
      discriminator:
        propertyName: componentType
    CreateHardwareComponentReq:
      required:
        - assetId
        - componentName
        - componentType
      type: object
      allOf:
        - "$ref": "#/components/schemas/CreateComponentReq"
        - type: object
          properties:
            hardwareTypeId:
              type: string
            configurationCode:
              maxLength: 255
              minLength: 0
              type: string
            settingsVersion:
              maxLength: 64
              minLength: 0
              type: string
            serialOne:
              maxLength: 128
              minLength: 0
              type: string
            serialTwo:
              maxLength: 128
              minLength: 0
              type: string
            macAddress:
              type: string
            ipAddress:
              type: string
            networkMask:
              type: string
            manufacturingDate:
              type: string
              format: date-time
            warrantyStatus:
              type: string
              enum:
                - Active
                - Expired
                - Unknown
            recallAnnounced:
              type: boolean
            slot:
              type: string
    CreateSoftwareComponentReq:
      required:
        - assetId
        - componentName
        - componentType
      type: object
      allOf:
        - "$ref": "#/components/schemas/CreateComponentReq"
        - type: object
          properties:
            softwareTypeId:
              type: string
            installedVersion:
              type: string
            baselineVersion:
              type: string
            releaseDate:
              type: string
              format: date-time
    UpdateComponentReq:
      required:
        - componentType
      type: object
      properties:
        componentType:
          type: string
          enum:
            - SOFTWARE
            - HARDWARE
        componentId:
          maxLength: 128
          minLength: 0
          type: string
        componentName:
          maxLength: 255
          minLength: 1
          type: string
        componentDescription:
          maxLength: 255
          minLength: 1
          type: string
        sapOrderNumber:
          type: string
        parentComponentId:
          type: string
        productId:
          type: string
        productVariantId:
          type: string
        additionalComponentInformation:
          type: string
      discriminator:
        propertyName: componentType
    UpdateHardwareComponentReq:
      required:
        - componentType
      type: object
      allOf:
        - "$ref": "#/components/schemas/UpdateComponentReq"
        - type: object
          properties:
            hardwareTypeId:
              type: string
            configurationCode:
              type: string
            settingsVersion:
              type: string
            serialOne:
              type: string
            serialTwo:
              type: string
            macAddress:
              type: string
            ipAddress:
              type: string
            networkMask:
              type: string
            manufacturingDate:
              type: string
              format: date-time
            warrantyStatus:
              type: string
              enum:
                - Active
                - Expired
                - Unknown
            recallAnnounced:
              type: boolean
            slot:
              type: string
    UpdateSoftwareComponentReq:
      required:
        - componentType
      type: object
      allOf:
        - "$ref": "#/components/schemas/UpdateComponentReq"
        - type: object
          properties:
            softwareTypeId:
              type: string
            installedVersion:
              type: string
            baselineVersion:
              type: string
            releaseDate:
              type: string
              format: date-time
    CreateGeoCoordinateReq:
      type: object
      properties:
        latitude:
          type: number
          format: double
        longitude:
          type: number
          format: double
        altitude:
          type: number
          format: double
    CreateLocationReq:
      type: object
      properties:
        country:
          type: string
        city:
          type: string
        zipCode:
          type: string
        state:
          type: string
        street:
          type: string
        coordinates:
          "$ref": "#/components/schemas/CreateGeoCoordinateReq"
    CreateStationReq:
      required:
        - name
      type: object
      properties:
        name:
          maxLength: 255
          minLength: 1
          type: string
        description:
          maxLength: 1024
          minLength: 0
          type: string
        location:
          "$ref": "#/components/schemas/CreateLocationReq"
        tags:
          type: array
          items:
            "$ref": "#/components/schemas/CreateTagReq"
        thumbnailUrl:
          type: string
        subTenant:
          type: string
      description: Request for station creation
    UpdateGeoCoordinateReq:
      type: object
      properties:
        latitude:
          type: number
          format: double
        longitude:
          type: number
          format: double
        altitude:
          type: number
          format: double
    UpdateLocationReq:
      type: object
      properties:
        country:
          type: string
        city:
          type: string
        zipCode:
          type: string
        state:
          type: string
        street:
          type: string
        coordinates:
          "$ref": "#/components/schemas/UpdateGeoCoordinateReq"
    UpdateTagReq:
      required:
        - value
      type: object
      properties:
        value:
          maxLength: 255
          minLength: 1
          type: string
        id:
          type: string
    UpdateStationReq:
      required:
        - name
      type: object
      properties:
        name:
          maxLength: 255
          minLength: 1
          type: string
        location:
          "$ref": "#/components/schemas/UpdateLocationReq"
        tags:
          type: array
          items:
            "$ref": "#/components/schemas/UpdateTagReq"
        description:
          maxLength: 1024
          minLength: 0
          type: string
        thumbnailUrl:
          type: string
        subTenant:
          type: string
    ExtAssetExt:
      type: object
      properties:
        id:
          type: string
        createdAt:
          type: string
        lastUpdate:
          type: string
        assetName:
          type: string
        assetTypeId:
          type: string
        description:
          type: string
        commissioningDate:
          type: string
        operationalState:
          type: string
        processCriticality:
          type: string
        stationId:
          type: string
        mainHardwareComponentId:
          type: string
        mainSoftwareComponentId:
          type: string
    PageRspExtAssetExt:
      type: object
      properties:
        number:
          type: integer
          format: int32
        numberOfElements:
          type: integer
          format: int32
        size:
          type: integer
          format: int32
        totalElements:
          type: integer
          format: int64
        totalPages:
          type: integer
          format: int32
        elements:
          type: array
          items:
            "$ref": "#/components/schemas/ExtAssetExt"
        totalCount:
          type: integer
          format: int64
    SuccessRsp:
      type: object
      properties:
        success:
          type: string
    ExtSoftwareComponentExt:
      type: object
      properties:
        baselineVersion:
          type: string
        baselineVersionModifiedAt:
          type: string
          format: date-time
        installedVersion:
          type: string
        installedVersionModifiedAt:
          type: string
          format: date-time
        releaseDate:
          type: string
        softwareComponentTypeId:
          type: string
    ExtHardwareComponentExt:
      type: object
      properties:
        ipAddress:
          type: string
        macAddress:
          type: string
        networkMask:
          type: string
        manufacturingDate:
          type: string
        recallAnnounced:
          type: string
        warrantyStatus:
          type: string
        serialOne:
          type: string
        serialTwo:
          type: string
        configurationCode:
          type: string
        settingsVersion:
          type: string
        hardwareComponentTypeId:
          type: string
    ExtComponentExt:
      type: object
      properties:
        id:
          type: string
        createdAt:
          type: string
        lastUpdate:
          type: string
        active:
          type: string
        description:
          type: string
        componentId:
          type: string
        componentName:
          type: string
        mainComponent:
          type: string
        sapOrderNumber:
          type: string
        assetId:
          type: string
        parentComponentId:
          type: string
        typeOfConstruction:
          type: string
        softwareComponentExt:
          "$ref": "#/components/schemas/ExtSoftwareComponentExt"
        extHardwareComponentExt:
          "$ref": "#/components/schemas/ExtHardwareComponentExt"
        productModel:
          type: string
        productManufacturer:
          type: string
        productFamily:
          type: string
        productVariant:
          type: string
        articleNumber:
          type: string
        lifeCycleStatus:
          type: string
        productVariantBaseline:
          type: string
    PageRsp:
      type: object
      properties:
        number:
          type: integer
          format: int32
        numberOfElements:
          type: integer
          format: int32
        size:
          type: integer
          format: int32
        totalElements:
          type: integer
          format: int64
        totalPages:
          type: integer
          format: int32
        elements:
          type: array
          items:
            type: object
        totalCount:
          type: integer
          format: int64
    GeoCoordinateExt:
      type: object
      properties:
        latitude:
          type: number
          format: double
        longitude:
          type: number
          format: double
        altitude:
          type: number
          format: double
    LocationExt:
      type: object
      properties:
        country:
          type: string
        city:
          type: string
        zipCode:
          type: string
        state:
          type: string
        street:
          type: string
    ExtStationExt:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        createdAt:
          type: string
        lastUpdate:
          type: string
        location:
          "$ref": "#/components/schemas/LocationExt"
        coordinates:
          type: array
          items:
            "$ref": "#/components/schemas/GeoCoordinateExt"
    BulkErrorRsp:
      type: object
      properties:
        fieldName:
          type: string
        reason:
          type: string
    DeleteBulkRsp:
      type: object
      properties:
        totalDeletedCount:
          type: integer
          format: int64
        deleteErrors:
          type: array
          items:
            "$ref": "#/components/schemas/BulkErrorRsp"
