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.