openapi: 3.0.0 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 basePath: "/api/messagebroker/v5" servers: - url: "https://{subdomain}.{region}.mindsphere.io/api/messagebroker/v5/" description: MindSphere Gateway base url to call the API. 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:

Code Suffix Message
subscriberIdTooLong Given subscribers id must not be longer than 255 character.
versionIdTooLong Given version id must not be longer than 250 character.
topicIdFormatInvalid Given topic id does not match the required format.
topicIdTooLong Given topic id must not be longer than 255 character.
topicNotExistsAtPostboxSubscription Topic must exist before subscribing to postbox topic.
uriNotValid uri must be valid MindSphere Gateway uri.
subscriberIdMismatch Given subscriber id should be equal to application name in the uri.
content: application/json: schema: $ref: "#/components/schemas/Errors" "404": description: | Not found. Possible errors:

Code Suffix Message
TopicNotFound Topic is not found.
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:

Code Suffix Message
SubscriptionNotFound Subscription is not found.
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:

Code Suffix Message
SubscriptionNotFound Subscription is not found.
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 postbox 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:

Code Suffix Message
topicIdFormatInvalid Given topic id does not match the required format.
topicIdTooLong Given topic id must not be longer than 255 character.
topicDoesNotExist Topic must be created before posting a message.
contentTooLong Message size must be in the range provided by cloud providers.
content: application/json: schema: $ref: "#/components/schemas/Errors" "403": description: | Forbidden. Possible errors:

Code Suffix Message
insufficientPermissions The caller doesn't have sufficient permissions to post messages into the given topic.
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://gateway.eu1.mindsphere.io/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." 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.