openapi: 3.0.1
info:
  version: '3.0.2'
  x-visibility: external
  title: Message Broker API
  description: >
    Message Broker is a service that enables asynchronous communication in the platform, that can be used to decouple applications and services from each other.

    ### Generic Errors

    The following generic error codes might occur at any of the specified operations. Generic errors are prefixed with 'mdsp.core.generic.'.

      - 400: invalidParameter
      - 400: invalidRequestBodyProperty
      - 401: unauthorized
      - 403: forbidden
      - 404: noMatch
      - 429: tooManyRequests
      - 500: internalServerError

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

tags:
  - name: Subscribers
    description: Managing subscribers.
  - name: Messages
    description: Posting Message.

paths:
  "/subscribers/{id}/versions/{versionId}/topics/{topicId}":
    put:
      tags:
        - Subscribers
      summary: Create or update a subscription to the given topic.
      description: Create or update a subscription to the given topic. After a successful subscription, the subscriber can receive messages from the given topic over the webhook uri. Webhook uri should provide support for http post operation only.
      operationId: createOrUpdateSubscription
      x-permissions: [ mb.s.w ]
      parameters:
        - $ref: "#/components/parameters/SubscriberId"
        - $ref: "#/components/parameters/SubscriberVersionId"
        - $ref: "#/components/parameters/SubscriberTopicId"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SubscriberTopicInput"
        description: Input for creating or updating a subscription to a topic.
        required: true
      responses:
        "200":
          description: Subscription has been updated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SubscriberTopicInput"
        "201":
          description: Subscription has been created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SubscriberTopicInput"
        "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>subscriberIdTooLong</td>
                <td>Given subscribers id must not be longer than 255 character.</td>
              </tr>
              <tr>
                <td>versionIdTooLong</td>
                <td>Given version id must not be longer than 250 character.</td>
              </tr>
              <tr>
                <td>topicIdFormatInvalid</td>
                <td>Given topic id does not match the required format.</td>
              </tr>
              <tr>
                <td>topicIdTooLong</td>
                <td>Given topic id must not be longer than 255 character.</td>
              </tr>
              <tr>
                <td>topicNotExistsAtPostboxSubscription</td>
                <td>Topic must exist before subscribing to postbox topic.</td>
              </tr>
              <tr>
                <td>uriNotValid</td>
                <td>uri must be valid FDS Gateway uri.</td>
              </tr>
              <tr>
                <td>subscriberIdMismatch</td>
                <td>Given subscriber id should be equal to application name in the uri.</td>
              </tr>
            </table>
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Errors"
        "404":
          description: |
            Not found. Possible errors:
            <br><br>
            <table>
              <colgroup>
                <col span="1" style="width: 40%;">
                <col span="1" style="width: 60%;">
              </colgroup>
              <tr>
                <th align="left">Code Suffix</th>
                <th align="left">Message</th>
              </tr>
              <tr>
                <td>TopicNotFound</td>
                <td>Topic is not found.</td>
              </tr>
            </table>
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Errors"
        "default":
          $ref: "#/components/responses/default"

    get:
      tags:
        - Subscribers
      summary: Get the subscription.
      description: Get the subscription.
      operationId: retrieveSubscription
      x-permissions: [ mb.s.r ]
      parameters:
        - $ref: "#/components/parameters/SubscriberId"
        - $ref: "#/components/parameters/SubscriberVersionId"
        - $ref: "#/components/parameters/SubscriberTopicId"
      responses:
        "200":
          description: Returns the subscription to the given topic.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SubscriberTopicInput"
        "404":
          description: |
            Not found. Possible errors:
            <br><br>
            <table>
              <colgroup>
                <col span="1" style="width: 40%;">
                <col span="1" style="width: 60%;">
              </colgroup>
              <tr>
                <th align="left">Code Suffix</th>
                <th align="left">Message</th>
              </tr>
              <tr>
                <td>SubscriptionNotFound</td>
                <td>Subscription is not found.</td>
              </tr>
            </table>
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Errors"
        "default":
          $ref: "#/components/responses/default"

    delete:
      tags:
        - Subscribers
      summary: Delete the given subscription.
      description: Delete the given subscription.
      operationId: deleteSubscription
      x-permissions: [ mb.n.d ]
      parameters:
        - $ref: "#/components/parameters/SubscriberId"
        - $ref: "#/components/parameters/SubscriberVersionId"
        - $ref: "#/components/parameters/SubscriberTopicId"
      responses:
        "204":
          description: Subscription has been deleted.
        "404":
          description: |
            Not found. Possible errors:
            <br><br>
            <table>
              <colgroup>
                <col span="1" style="width: 40%;">
                <col span="1" style="width: 60%;">
              </colgroup>
              <tr>
                <th align="left">Code Suffix</th>
                <th align="left">Message</th>
              </tr>
              <tr>
                <td>SubscriptionNotFound</td>
                <td>Subscription is not found.</td>
              </tr>
            </table>
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Errors"
        "default":
          $ref: "#/components/responses/default"

  "/topics/{id}/sendmessage":
    post:
      tags:
        - Messages
      summary: Publishes new message to the given topic.
      operationId: publishMessageToTopic
      x-permissions: [ mb.t.m.w ]
      parameters:
        - $ref: "#/components/parameters/topicId"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Messages"
        description: Input for posting a message on given <B>postbox</B> topic only. The content is what the sender sends and is not modified.
        required: true
      responses:
        "201":
          description: No content.
        "400":
          description: |
            Bad request. Possible errors:
            <br><br>
            <table>
              <colgroup>
                <col span="1" style="width: 30%;">
                <col span="1" style="width: 70%;">
              </colgroup>
              <tr>
                <th align="left">Code Suffix</th>
                <th align="left">Message</th>
              </tr>
              <tr>
                <td>topicIdFormatInvalid</td>
                <td>Given topic id does not match the required format.</td>
              </tr>
              <tr>
                <td>topicIdTooLong</td>
                <td>Given topic id must not be longer than 255 character.</td>
              </tr>
              <tr>
                <td>topicDoesNotExist</td>
                <td>Topic must be created before posting a message.</td>
              </tr>
              <tr>
                <td>contentTooLong</td>
                <td>Message size must be in the range provided by cloud providers.</td>
              </tr>
            </table>
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Errors"
        "403":
          description: |
            Forbidden. Possible errors:
            <br><br>
            <table>
              <colgroup>
                <col span="1" style="width: 30%;">
                <col span="1" style="width: 70%;">
              </colgroup>
              <tr>
                <th align="left">Code Suffix</th>
                <th align="left">Message</th>
              </tr>
              <tr>
                <td>insufficientPermissions</td>
                <td>The caller doesn't have sufficient permissions to post messages into the given topic.</td>
              </tr>
            </table>
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Errors"
        "default":
          $ref: "#/components/responses/default"

components:
  schemas:
    TopicId:
      type: string
      description: "Id of the topic. Format: mdsp.{tenant}.{service}.v{version}.{type}.{additional}"
      pattern: mdsp\.[a-z0-9-_]+\.[a-z0-9-_]+\.v[0-9]+\.(pubsub|postbox)\.[a-z0-9-_.]+
      maxLength: 255
      example: mdsp.core.am.v1.postbox.asset.deleted

    Messages:
      type: object
      properties:
        content:
          type: string
          description: Message to publish.
          example: "string"

    WebHookURL:
      type: string
      description: Gateway uri on which the app will receive notifications.
      maxLength: 2000
      example: "https://api.eu1.siemens.app/api/thirdpartyapp-tenantname/v1/mywebhookURL"

    SubscriberTopicInput:
      type: object
      properties:
        uri:
          $ref: "#/components/schemas/WebHookURL"
      required:
        - uri

    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. Every code is bound to one message."
                format: "mdsp.core.messagebroker.<suffix>"
                example: "mdsp.core.messagebroker.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:
    topicId:
      name: id
      in: path
      description: "Id of the topic. Format: mdsp.{tenant}.{service}.v{version}.{type}.{additional}"
      required: true
      schema:
        $ref: "#/components/schemas/TopicId"

    SubscriberId:
      name: id
      in: path
      description: Id of the subscriber.
      required: true
      example: thirdpartyapp
      schema:
        type: string
        pattern: /[a-zA-Z0-9-_.]+/
        maxLength: 255

    SubscriberTopicId:
      name: topicId
      in: path
      description: Id of the topic that the subscriber subscribes to.
      required: true
      schema:
        $ref: "#/components/schemas/TopicId"

    SubscriberVersionId:
      name: versionId
      in: path
      description: Version of the subscriber.
      required: true
      example: "v1"
      schema:
        type: string
        pattern: /[a-zA-Z0-9-_.]+/
        maxLength: 250

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

  securitySchemes:
    oauth2:
      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: {}
