openapi: 3.0.1
info:
  version: 1.0.1
  x-visibility: internal
  title: Bring your own data API
  description: |
    Bring your own data API.

servers:
  - url: https://api.eu1.siemens.app/customTopicRegistrations-1000001700/v3
    description: Xcelerator compliant URL

tags:
  - name: Custom Topic Registration
    description: Managing Rules.

paths:
  /customTopicRegistrations:
    post:
      tags:
        - Custom Topic Registration
      summary: Create mapping.
      description: Create Mapping for IH.
      operationId: createDataMappings
      x-permissions:
        - mcmq.m.c
      requestBody:
        description: Input for Custom Data Mapping.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MappingInput'
      responses:
        '201':
          description: Mapping has been created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MappingResource'
        '400':
          description: |
            Bad request. Possible errors:
            <br><br>
            <table>
              <colgroup>
                <col span="1" style="width: 50%;">
                <col span="1" style="width: 50%;">
              </colgroup>
              <tr>
                <th align="left">Code Suffix</th>
                <th align="left">Message</th>
              </tr>
              <tr>
                <td>functionFormatError</td>
                <td>Given app name does not match the required format.</td>
              </tr>
              <tr>
                <td>projectNameTooLong</td>
                <td>Given project name must not be longer than 255 character.</td>
              </tr>
            </table>
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        default:
          $ref: '#/components/responses/default'
    get:
      tags:
        - Custom Topic Registration
      summary: Get all custom data mappings.
      description: Get All Custom Data Mappings
      operationId: getAllMappings
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/size'
      x-permissions:
        - mcmq.m.r
      responses:
        '200':
          description: Returns all custom data mappings.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MappingResource'
        default:
          $ref: '#/components/responses/default'

  /customTopicRegistrations/{id}:
    get:
      tags:
        - Custom Topic Registration
      summary: Get all custom data mappings.
      description: Get All Custom Data Mappings
      operationId: getSingle
      parameters:
        - $ref: '#/components/parameters/id'
      x-permissions:
        - mcmq.m.r
      responses:
        '200':
          description: Returns all custom data mappings.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MappingInput'
        default:
          $ref: '#/components/responses/default'
    patch:
      tags:
        - Custom Topic Registration
      summary: Update a Custom Data Mapping.
      description: Patch existing Topic registration
      operationId: UpdateCustomDataMapping
      x-permissions:
        - mcmq.m.u
      parameters:
        - $ref: '#/components/parameters/id'
        - $ref: '#/components/parameters/ifMatch'
      requestBody:
        description: Input for Publisher.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchMappingInput'
      responses:
        '200':
          description: Custom Data Mapping has been updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MappingResource'
        '400':
          description: |
            Bad request. Possible errors:
            <br><br>
            <table>
              <colgroup>
                <col span="1" style="width: 50%;">
                <col span="1" style="width: 50%;">
              </colgroup>
              <tr>
                <th align="left">Code Suffix</th>
                <th align="left">Message</th>
              </tr>
              <tr>
                <td>functionFormatError</td>
                <td>Given app name does not match the required format.</td>
              </tr>
              <tr>
                <td>projectNameTooLong</td>
                <td>Given project name must not be longer than 255 character.</td>
              </tr>
            </table>
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        default:
          $ref: '#/components/responses/default'
    delete:
      tags:
        - Custom Topic Registration
      summary: Delete the custom data mapping.
      description: Delete the custom data mapping.
      operationId: deleteCustomDataMapping1
      x-permissions:
        - mcmq.m.d
      parameters:
        - $ref: '#/components/parameters/id'
        - $ref: '#/components/parameters/ifMatch'
      responses:
        '204':
          description: Mapping has been deleted.
        default:
          $ref: '#/components/responses/default'

  /customTopicRegistrations/{id}/mappings:
    post:
      tags:
        - Custom Topic Registration
      summary: Create mapping.
      description: Create Mapping for IH.
      operationId: createDataMappings1
      x-permissions:
        - mcmq.m.c
      parameters:
        - $ref: '#/components/parameters/id'
      requestBody:
        description: Input for Custom Data Mapping.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomMappingInformation'
      responses:
        '201':
          description: Mapping has been created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomMappingInformation'
        '400':
          description: |
            Bad request. Possible errors:
            <br><br>
            <table>
              <colgroup>
                <col span="1" style="width: 50%;">
                <col span="1" style="width: 50%;">
              </colgroup>
              <tr>
                <th align="left">Code Suffix</th>
                <th align="left">Message</th>
              </tr>
              <tr>
                <td>functionFormatError</td>
                <td>Given app name does not match the required format.</td>
              </tr>
              <tr>
                <td>projectNameTooLong</td>
                <td>Given project name must not be longer than 255 character.</td>
              </tr>
            </table>
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        default:
          $ref: '#/components/responses/default'
    get:
      tags:
        - Custom Topic Registration
      summary: Get single custom data mapping.
      description: Get a custom data mapping for given id.
      operationId: GetSingleCustomDataMapping
      parameters:
        - $ref: '#/components/parameters/id'
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/size'
      x-permissions:
        - mcmq.m.r
      responses:
        '200':
          description: Returns a custom data mapping for given id.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MappingInformationList'
        default:
          $ref: '#/components/responses/default'

  /customTopicRegistrations/{id}/mappings/{mappingId}:
    get:
      tags:
        - Custom Topic Registration
      summary: Get single custom data mapping.
      description: Get a custom data mapping for given id.
      operationId: GetSingleCustomDataMapping1
      parameters:
        - $ref: '#/components/parameters/id'
        - $ref: '#/components/parameters/mappingId'
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/size'
      x-permissions:
        - mcmq.m.r
      responses:
        '200':
          description: Returns a custom data mapping for given id.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MappingInformation'
        default:
          $ref: '#/components/responses/default'
    delete:
      tags:
        - Custom Topic Registration
      summary: Delete the custom data mapping.
      description: Delete the custom data mapping.
      operationId: deleteCustomDataMapping
      x-permissions:
        - mcmq.m.d
      parameters:
        - $ref: '#/components/parameters/id'
        - $ref: '#/components/parameters/mappingId'
        - $ref: '#/components/parameters/ifMatch'
      responses:
        '204':
          description: Mapping has been deleted.
        default:
          $ref: '#/components/responses/default'

components:
  schemas:
    AssetInformation:
      type: object
      properties:
        assetId:
          $ref: '#/components/schemas/AssetId'
        aspectName:
          $ref: '#/components/schemas/AspectName'
        variables:
          type: array
          items:
            $ref: '#/components/schemas/VariableDefition'

    MappingInformation:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/Id'
        identifier:
          $ref: '#/components/schemas/CustomDataIdentifier'
        agentId:
          $ref: '#/components/schemas/AgentId'
        assetId:
          $ref: '#/components/schemas/AssetId'
        aspectName:
          $ref: '#/components/schemas/AspectName'
        variableName:
          $ref: '#/components/schemas/VariableName'
        variableValueExpression:
          $ref: '#/components/schemas/RuleOfValue'
        variableTimestampExpression:
          $ref: '#/components/schemas/RuleOfTime'
        timeConverter:
          $ref: '#/components/schemas/TimeConverter'

    CustomMappingInformation:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/Id'
        assetId:
          $ref: '#/components/schemas/AssetId'
        aspectName:
          $ref: '#/components/schemas/AspectName'
        variableName:
          $ref: '#/components/schemas/VariableName'
        variableValueExpression:
          $ref: '#/components/schemas/RuleOfValue'
        variableTimestampExpression:
          $ref: '#/components/schemas/RuleOfTime'
        timeConverter:
          $ref: '#/components/schemas/TimeConverter'

    MQTTClientId:
      type: string
      description: Id of mqtt client.
      maxLength: 255
      example: '<tenant>_Client001'

    AssetId:
      type: string
      description: Id of Asset.
      maxLength: 255
      example: SomeAssetId

    AspectName:
      type: string
      description: Id of Aspect.
      maxLength: 255
      example: SomeAspectName

    DataPointId:
      type: string
      description: Id of DataPoint
      maxLength: 255
      example: SomeDataPointId

    VariableDefition:
      type: object
      properties:
        name:
          $ref: '#/components/schemas/VariableName'
        valueExpression:
          $ref: '#/components/schemas/RuleOfValue'
        timestampExpression:
          $ref: '#/components/schemas/RuleOfTime'

    TimeConverter:
      type: string
      enum:
        - fromEpoch
        - fromUnixTimestamp
        - fromRFC2822
        - fromRFC822
        - fromRFC3339
        - fromMySQLTimestamp
        - fromHumanReadableFormat
        - fromJavaScriptDateFormat

    VariableName:
      type: string
      description: Name of variable.
      maxLength: 255
      example: Temperature

    RuleOfValue:
      type: string
      description: Rule of variable's value.
      maxLength: 255
      example: >-
        [?propertyId=='lorawan-v1-0-8ivhglxiqhw0-hiu-temperature-1urbh5bx6n'].value
        | [*]

    RuleOfTime:
      type: string
      description: Rule of variable's value.
      maxLength: 255
      example: >-
        [?propertyId=='lorawan-v1-0-8ivhglxiqhw0-hiu-temperature-1urbh5bx6n'].timestamp
        | [*]

    TopicDefinition:
      type: string
      description: Topic structure definition.
      maxLength: 255
      example: firstfloor/<tenant>_Client001/timeseries

    CustomDataIdentifier:
      type: string
      description: Topic structure definition.
      maxLength: 255
      example: UUID

    AgentId:
      type: string
      description: Id of agent.
      maxLength: 255
      example: 3asd2d3ddfk523dkas

    Id:
      type: string
      description: Id.
      maxLength: 255
      example: SomeId
      readOnly: true

    RequestId:
      type: string
      description: Id.
      maxLength: 255
      example: SomeId

    etag:
      type: string
      description: ETag number of resource.
      maxLength: 32
      example: '0'
      readOnly: true

    MappingInput:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/Id'
        mqttClientId:
          $ref: '#/components/schemas/MQTTClientId'
        topic:
          $ref: '#/components/schemas/TopicDefinition'
        eTag:
          $ref: '#/components/schemas/etag'

    PatchMappingInput:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/Id'
        topic:
          $ref: '#/components/schemas/TopicDefinition'
        eTag:
          $ref: '#/components/schemas/etag'

    CustomRuleInput:
      type: object
      properties:
        expressions:
          type: array
          items:
            $ref: '#/components/schemas/AssetInformation'
        customDataIdentifier:
          $ref: '#/components/schemas/CustomDataIdentifier'
        agentId:
          $ref: '#/components/schemas/AgentId'
        timeConverter:
          $ref: '#/components/schemas/TimeConverter'

    MappingResource:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/Id'
        mqttClientId:
          $ref: '#/components/schemas/MQTTClientId'
        topic:
          $ref: '#/components/schemas/TopicDefinition'
        eTag:
          $ref: '#/components/schemas/etag'

    CustomDataRuleResource:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/Id'
        name:
          $ref: '#/components/schemas/VariableName'
        valueExpression:
          $ref: '#/components/schemas/RuleOfValue'
        timestampExpression:
          $ref: '#/components/schemas/RuleOfTime'
        datapointId:
          $ref: '#/components/schemas/DataPointId'
        timeConverter:
          $ref: '#/components/schemas/TimeConverter'
        eTag:
          $ref: '#/components/schemas/etag'

    CustomRuleResource:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/Id'
        expressions:
          type: array
          items:
            $ref: '#/components/schemas/AssetInformation'
        customDataIdentifier:
          $ref: '#/components/schemas/CustomDataIdentifier'
        agentId:
          $ref: '#/components/schemas/AgentId'
        timeConverter:
          $ref: '#/components/schemas/TimeConverter'
        eTag:
          $ref: '#/components/schemas/etag'

    MappingInformationList:
      type: object
      properties:
        content:
          type: array
          items:
            $ref: '#/components/schemas/MappingInformation'
        page:
          $ref: '#/components/schemas/Page'

    CustomDataListResource:
      type: object
      properties:
        content:
          type: array
          items:
            $ref: '#/components/schemas/MappingInformation'
        page:
          $ref: '#/components/schemas/Page'

    PageToken:
      title: Page
      type: object
      properties:
        nextToken:
          type: string
          readOnly: true
          example: 4eeb12063e15484fb91cd64deadbeefd9d91c342b625471d8c84084e489191de

    CustomDataRuleResourcePage:
      title: CustomDataRuleResource
      type: object
      description: A paged list of events
      properties:
        rules:
          type: array
          items:
            $ref: '#/components/schemas/CustomDataRuleResource'
        page:
          $ref: '#/components/schemas/PageToken'
      required:
        - rules
        - page

    Page:
      title: Page
      type: object
      properties:
        size:
          type: integer
          readOnly: true
          example: 20
          description: Number of elements in the current page.
        totalElements:
          type: integer
          readOnly: true
          example: 1
          description: Total number of elements.
        totalPages:
          type: integer
          readOnly: true
          example: 1
          description: Total number of pages based on size per page and total elements.
        number:
          type: integer
          readOnly: true
          example: 0
          description: Current page number.

    Errors:
      type: object
      description: Error response body model.
      properties:
        errors:
          type: array
          description: >-
            Concrete error codes and messages are defined at operation error
            response descriptions in this API specification.
          items:
            type: object
            properties:
              code:
                type: string
                description: Unique error code.
                format: mdsp.core.notification.<suffix>
                example: mdsp.core.notification.exampleCode
              logref:
                type: string
                description: Logging correlation ID for debugging purposes.
                example: 0bff7e7a-cd25-4576-9908-4180ef086174
              message:
                type: string
                description: Human readable error message in English.
                example: Description of the error's origin.
            required:
              - code
              - logref
              - message

  parameters:
    id:
      name: id
      in: path
      description: Id of handler.
      required: true
      schema:
        $ref: '#/components/schemas/RequestId'

    mappingId:
      name: mappingId
      in: path
      description: Id of mapping.
      required: true
      schema:
        $ref: '#/components/schemas/RequestId'

    requestId:
      name: requestId
      in: path
      description: Id of request.
      required: true
      schema:
        $ref: '#/components/schemas/RequestId'

    page:
      name: page
      in: query
      required: false
      schema:
        type: integer
        default: 0
        minimum: 0
        maximum: 1000

    size:
      name: size
      in: query
      required: false
      schema:
        type: integer
        default: 20
        minimum: 1
        maximum: 500

    nextToken:
      name: nextToken
      in: query
      required: false
      schema:
        type: string
      example: 4eeb12063e15484fb91cd64deadbeefd9d91c342b625471d8c84084e489191de

    ifNoneMatch:
      name: If-None-Match
      in: header
      description: >-
        This is an optional header, the only supported value is '*'. Using this
        header guarantees that an existing resource will not be overwritten. If
        the header is not present in the request, the existing resource is
        always overwritten.
      required: false
      example: '*'
      schema:
        type: string

    ifNoneMatchStar:
      name: If-None-Match
      in: header
      required: false
      schema:
        type: string
      description: Set ifNoneMatch header to "*" for ensuring create request

    ifMatch:
      name: If-Match
      in: header
      required: false
      schema:
        type: string
      description: |
        Last known version to facilitate optimistic locking.
        *Required for modification.

    agentIdInQuery:
      name: agentId
      in: query
      required: false
      schema:
        type: string
      description: |
        Id of agent.

    identifier:
      name: identifier
      in: query
      required: false
      schema:
        type: string
      description: |
        Identifier of custom data.

    agentIdQuery:
      name: agentId
      in: query
      required: false
      schema:
        type: string
      description: ''

    tenantContext:
      name: tenantContext
      in: header
      required: true
      schema:
        type: string
      example: mytenant
      description: >
        If notification is tenant specific, value of TenantContext should be
        specified. If notification is not tenant specific, value of
        TenantContext should be *, If tenant is core.

        If tenant is not core, using * will be ignored. Notifications are valid
        only for tenant in given token. Using different tenant in tenantContext
        is not allowed.

  responses:
    default:
      description: Other error with any status code and response body format.

  securitySchemes:
    customTopicRegistrations:
      type: oauth2
      description: |
        For **Xcelerator** compliance, please use **authorizationUrl** = https://1000001700.eu1.sws.siemens.com/oauth/authorize and **tokenUrl** = https://1000001700.eu1.sws.siemens.com/oauth/token

      flows:
        authorizationCode:
          authorizationUrl: 'https://1000001700.eu1.sws.siemens.com/oauth/authorize'
          tokenUrl: 'https://1000001700.eu1.sws.siemens.com/oauth/token'
          scopes:
            mcmq.tr.c: Permission to create topic registration
            mcmq.tr.r: Permission to read topic registration
            mcmq.tr.u: Permission to update topic registration
            mcmq.tr.d: Permission to delete topic registration