1. Overview

Enterprise Messaging - Messaging Management REST

1.2. URI scheme

Host : https://sap-cp-em-management-url
BasePath : /hub/rest/api/v1/management/messaging

1.3. Tags

  • messaging : Messaging Management

2. Resources

2.1. Messaging

Messaging Management

2.1.1. Get Queues

GET /hub/rest/api/v1/management/messaging/queues
Description

Get settings and information for all queues

Responses
HTTP Code Description Schema

200

Ok: Successfully retrieved list of queues

< Queue > array

401

Unauthorized: if the authorization failed

No Content

403

Forbidden: if the provided authentication credentials were insufficient

No Content

404

Not Found: if the queue was not found

No Content

Produces
  • application/json

2.1.2. Get Queue

GET /hub/rest/api/v1/management/messaging/queues/{queue}
Description

Get settings and information for queue

Parameters
Type Name Description Schema

Path

queue
required

Name of the queue (must be URL encoded) - pattern: ^[a-zA-Z0-9-_.]{1,111}(?:/[a-zA-Z0-9-_.]{1,109}){0,19}$

string

Responses
HTTP Code Description Schema

200

Ok: successfully retrieved the queue

Queue

400

Bad Request: if the given parameters have invalid values

No Content

401

Unauthorized: if the authorization failed

No Content

403

Forbidden: if the provided authentication credentials were insufficient

No Content

404

Not Found: if the queue was not found

No Content

Produces
  • application/json

2.1.3. Create / Update Queue

PUT /hub/rest/api/v1/management/messaging/queues/{queue}
Description

Creates or updates a queue by the parameters specified in the request body. The queue name (path segment/parameter) must be URL encoded.

Parameters
Type Name Description Schema

Path

queue
required

Name of the queue (must be URL encoded) - pattern: ^[a-zA-Z0-9-_.]{1,111}(?:/[a-zA-Z0-9-_.]{1,109}){0,19}$

string

Body

queueConfig
optional

queueConfig

QueueP

Responses
HTTP Code Description Schema

200

Ok: if the queue was successfully updated

Queue

201

Created: if the queue was successfully created

Queue

400

Bad Request: if the given parameters have invalid values

No Content

401

Unauthorized: if the authorization failed

No Content

403

Forbidden: if the provided authentication credentials were insufficient

No Content

404

Not Found: if the queue was not found

No Content

501

Not Implemented: if a queue update is requested but the corresponding plan (lite,dev) doesn’t support it

No Content

Consumes
  • application/json

2.1.4. Delete Queue

DELETE /hub/rest/api/v1/management/messaging/queues/{queue}
Description

Deletes a queue by the name given in the parameters. The queue name (path segment/parameter) must be URL encoded.

Parameters
Type Name Description Schema

Path

queue
required

Name of the queue (must be URL encoded) - pattern: ^[a-zA-Z0-9-_.]{1,111}(?:/[a-zA-Z0-9-_.]{1,109}){0,19}$

string

Responses
HTTP Code Description Schema

200

Ok: if the queue was successfully deleted

No Content

204

No Content: if the queue was successfully deleted

No Content

400

Bad Request: if the given parameters have invalid values

No Content

401

Unauthorized: if the authorization failed

No Content

403

Forbidden: if the provided authentication credentials were insufficient

No Content

404

Not Found: if the queue was not found

No Content

2.1.5. Get All Queue Statistics

GET /hub/rest/api/v1/management/messaging/queues/{queue}/statistics
Description

Get statistic information for a dedicated queue in the current service instance. The statistic information might not be live. I.e. putting a message into a queue might not be reflected immediately in the statistic data.
Supported plan: dedicated.

Parameters
Type Name Description Schema

Path

queue
required

Name of the queue (must be URL encoded) - pattern: ^[a-zA-Z0-9-_.]{1,111}(?:/[a-zA-Z0-9-_.]{1,109}){0,19}$

string

Responses
HTTP Code Description Schema

200

Ok: successfully retrieved the queue statistics

QueueStatistics

401

Unauthorized: if the authorization failed

No Content

403

Forbidden: if the provided authentication credentials were insufficient

No Content

404

Not found: retrieval of queue statistics unsuccessful

No Content

Produces
  • application/json

2.1.6. Get Queue Subscriptions

GET /hub/rest/api/v1/management/messaging/queues/{queue}/subscriptions
Description

Get list of queue subscriptions of a given queue name. The queue name (path segment/parameter) must be URL encoded.

Parameters
Type Name Description Schema

Path

queue
required

Name of the queue (must be URL encoded) - pattern: ^[a-zA-Z0-9-_.]{1,111}(?:/[a-zA-Z0-9-_.]{1,109}){0,19}$

string

Responses
HTTP Code Description Schema

200

Ok: if the queue subscriptions was already existent.

< QueueSubscription > array

201

Created: if the queue subscription was successfully created

< QueueSubscription > array

400

Bad Request: if the given parameters have invalid values

No Content

401

Unauthorized: if the authorization failed

No Content

403

Forbidden: if the provided authentication credentials were insufficient

No Content

404

Not Found: if the queue was not found

No Content

Produces
  • application/json

2.1.7. Create / Update Queue Subscriptions

PUT /hub/rest/api/v1/management/messaging/queues/{queue}/subscriptions/{topic}
Description

Creates or updates a queue subscription. The queue name and topic pattern (path segment/parameter) must be URL encoded.

Parameters
Type Name Description Schema

Path

queue
required

Name of the queue (must be URL encoded) - pattern: ^[a-zA-Z0-9-_.]{1,111}(?:/[a-zA-Z0-9-_.]{1,109}){0,19}$

string

Path

topic
required

Topic (Subscription) (must be URL encoded) - pattern: $|(?=.{1,111}$)(?=(?:[^/]/?){1,19}$)(?:[A-Za-z0-9]|)(?:/(?:[A-Za-z0-9]|+))(?:/*)?$

string

Responses
HTTP Code Description Schema

200

Ok: if the queue subscription was successfully updated

QueueSubscription

201

Created: if the queue subscription was successfully created

QueueSubscription

400

Bad Request: if the given parameters have invalid values

No Content

401

Unauthorized: if the authorization failed

No Content

403

Forbidden: if the provided authentication credentials were insufficient

No Content

404

Not Found: if the queue was not found

No Content

501

Not Implemented: If the specific messaging does not support queue subscription updates

No Content

Consumes
  • application/json

2.1.8. Delete Queue Subscription

DELETE /hub/rest/api/v1/management/messaging/queues/{queue}/subscriptions/{topic}
Description

Deletes given queue subscription. The queue name and topic pattern (path segment/parameter) must be URL encoded.

Parameters
Type Name Description Schema

Path

queue
required

Name of the queue (must be URL encoded) - pattern: ^[a-zA-Z0-9-_.]{1,111}(?:/[a-zA-Z0-9-_.]{1,109}){0,19}$

string

Path

topic
required

Topic (Subscription) (must be URL encoded) - pattern: $|(?=.{1,111}$)(?=(?:[^/]/?){1,19}$)(?:[A-Za-z0-9]|)(?:/(?:[A-Za-z0-9]|+))(?:/*)?$

string

Responses
HTTP Code Description Schema

200

Ok: if the queue subscription was successfully deleted

No Content

204

No Content: if the queue subscription was successfully deleted

No Content

400

Bad Request: if the given parameters have invalid values

No Content

401

Unauthorized: if the authorization failed

No Content

403

Forbidden: if the provided authentication credentials were insufficient

No Content

404

Not Found: if the queue was not found

No Content

2.1.9. Get All Queues Statistics

GET /hub/rest/api/v1/management/messaging/queuesStatistics
Description

Get queue statistics for all queues of the service instance. The statistic information might not be live. I.e. putting a message into a queue might not be reflected immediately in the statistic data.
Supported plan: dedicated.

Responses
HTTP Code Description Schema

200

Ok: successfully retrieved the queue statistics

< QueueStatistics > array

401

Unauthorized: if the authorization failed

No Content

403

Forbidden: if the provided authentication credentials were insufficient

No Content

404

Not found: retrieval of queue statistics unsuccessful

No Content

Produces
  • application/json

2.1.10. Readiness Check

GET /hub/rest/api/v1/management/messaging/readinessCheck
Description

The check is required for SaaS provider to verify whether the provisioning for subscribers have already been done and whether preparations can be performed or not. It is highly recommended that every SaaS provider performs the readiness check before performing onboarding activities e.g. queue creation. If the subscription is the first interaction of the consumer with Enterprise Messaging there is a certain delay until the service is ready for usage. This API MUST NOT be called in a high frequency. Make use of the Retry-After header for polling.

Responses
HTTP Code Description Schema

200

Ok: Service is ready and can be used for messaging and management (incl. subscriptions)

string

401

Unauthorized

No Content

403

Forbidden

No Content

404

Not Found

No Content

503

Service Unavailable: The service is temporarily unavailable.
Headers :
Retry-After (integer (int32)) : Indicates how long the service is expected to be unavailable in seconds.

No Content

Produces
  • application/json

2.1.11. Get Resource Usage

GET /hub/rest/api/v1/management/messaging/resourceusage
Description

Get the current broker resource usage. The information might not be live since it is a spot check.
Supported plan: dedicated.

Responses
HTTP Code Description Schema

200

Ok: successfully retrieved the resource usage

ResourceUsage

401

Unauthorized: if the authorization failed

No Content

403

Forbidden: if the provided authentication credentials were insufficient

No Content

404

Not found: retrieval of broker resource usage unsuccessful

No Content

Produces
  • application/json

2.1.12. Get Broker Statistics

GET /hub/rest/api/v1/management/messaging/statistics
Description

Get statistics for the broker resource. The statistic information might not be live. I.e putting a message into the queue might not be reflected immediately in the statistic data.
Supported plan: dedicated.

Responses
HTTP Code Description Schema

200

Ok: successfully retrieved the broker statistics

Statistics

401

Unauthorized: if the authorization failed

No Content

403

Forbidden: if the provided authentication credentials were insufficient

No Content

404

Not found: retrieval of broker statistics unsuccessful

No Content

Produces
  • application/json

3. Definitions

3.1. Queue

Name Description Schema

accessType
optional

A queue has an access type, which determines how messages are delivered when multiple consumer flows are bound to it. Queues can be assigned one of the following access types
EXCLUSIVE: Only one consumer can receive a message at any one time, while additional consumers may be connected as standby. That is, only one Flow can be active. Only the first consumer to bind can receive messages. If the first consumer disconnects, the second consumer receives data, and so on. An exclusive queue always delivers messages in the order they are received.
NON_EXCLUSIVE: Multiple consumers can bind to a non-exclusive queue. Each consumer is serviced in round-robin fashion. This provides load-balancing; however, if a connection fails, then unacknowledged messages are delivered to another consumer with the re-delivered flag set. In this way, messages can be delivered to consumers out of order.
The access type can be changed for a durable queue, but only when client access to the queue has been disabled.
The default value is: NON_EXCLUSIVE.

Supported plans: default, dedicated.
Example : "EXCLUSIVE"

enum (EXCLUSIVE, NON_EXCLUSIVE)

maxDeliveredUnackedMsgsPerFlow
optional

Maximum number of unacknowledged messages allowed in the queue. The default value is: 10000.

Supported plans: default, dedicated.

integer (int64)

maxMessageSizeInBytes
optional

Maximum message size allowed in the queue (in bytes). The default value is: 10000000.

Supported plans: default, dedicated.

integer (int64)

maxQueueMessageCount
optional

Maximum allowed messages in the queue.

integer (int64)

maxQueueSizeInBytes
optional

Maximum allowed queue size (in bytes).
The default value is: 1572864000 in (binary) which equates to 1500 megabytes.
The value will always be rounded(ceiling) to a multiple of 1048576.
1048576 equates to 1 megabyte.

integer (int64)

messageCount
optional

Current number of messages residing in the queue.

Supported plans: default, dedicated.

integer (int64)

name
required

Name of the queue.

string

queueSizeInBytes
optional

Total size of messages in the queue (in bytes).

Supported plans: default, dedicated.

integer (int64)

respectTtlEnabled
optional

Enable or disable the respecting of the "time to live" (TTL). If enabled, then messages contained in the Queue are checked for expiry. If expired, the message is removed from the Queue and discarded. The default value is false

Supported plans: default, dedicated.

boolean

unacknowledgedMessageCount
optional

Total count of unacknowledged messages in the queue.

Supported plans: default, dedicated.

integer (int64)

3.2. QueueP

Name Description Schema

accessType
optional

A queue has an access type, which determines how messages are delivered when multiple consumer flows are bound to it. Queues can be assigned one of the following access types
EXCLUSIVE: Only one consumer can receive a message at any one time, while additional consumers may be connected as standby. That is, only one Flow can be active. Only the first consumer to bind can receive messages. If the first consumer disconnects, the second consumer receives data, and so on. An exclusive queue always delivers messages in the order they are received.
NON_EXCLUSIVE: Multiple consumers can bind to a non-exclusive queue. Each consumer is serviced in round-robin fashion. This provides load-balancing; however, if a connection fails, then unacknowledged messages are delivered to another consumer with the re-delivered flag set. In this way, messages can be delivered to consumers out of order.
The access type can be changed for a durable queue, but only when client access to the queue has been disabled.
The default value is: NON_EXCLUSIVE.

Supported plans: default, dedicated.
Example : "EXCLUSIVE"

enum (EXCLUSIVE, NON_EXCLUSIVE)

maxDeliveredUnackedMsgsPerFlow
optional

Maximum number of unacknowledged messages allowed in the queue. The default value is: 10000.

Supported plans: default, dedicated.

integer (int64)

maxMessageSizeInBytes
optional

Maximum message size allowed in the queue (in bytes). The default value is: 10000000.

Supported plans: default, dedicated.

integer (int64)

maxQueueMessageCount
optional

Maximum allowed messages in the queue.
Supported plans: dev, lite.

integer (int64)

maxQueueSizeInBytes
optional

Maximum allowed queue size (in bytes).
The default value is: 1572864000 in (binary) which equates to 1500 megabytes.
The value will always be rounded(ceiling) to a multiple of 1048576.
1048576 equates to 1 megabyte.
Supported plans: default, dedicated.

integer (int64)

respectTTL
optional

Enable or disable the respecting of the "time to live" (TTL). If enabled, then messages contained in the Queue are checked for expiry. If expired, the message is removed from the Queue and discarded. The default value is false

Supported plans: default, dedicated.

boolean

3.3. QueueStatistics

Name Description Schema

maxQueueSizeInBytes
optional

The maximum allowed queue size in bytes

integer (int64)

name
optional

Name of queue

string

queueSize
optional

The current amount of messages residing in the queue

integer (int64)

queueSizeInBytes
optional

The current queue size in bytes

integer (int64)

3.4. QueueSubscription

Name Description Schema

queueName
required

Name of the queue

string

topicPattern
required

Topic pattern

string

3.5. ResourceThreshold

Supported plan: dedicated

Name Description Schema

clearPercentage
optional

The clear threshold percentage expressed as a percentage (from 0 to 100) of the maximum number. The default value is 60

integer (int64)

clearValue
optional

The clear threshold expressed as a count value

integer (int64)

name
optional

Client profile name

string

setPercentage
optional

The set threshold value expressed as a percentage (from 0 to 100) of the maximum number. The default value is 80

integer (int64)

setValue
optional

The set threshold expressed as a count value

integer (int64)

3.6. ResourceUsage

Broker resource usage.
Supported plan: dedicated.

Name Description Schema

currentEgressFlows
optional

Current number of outgoing connections

integer (int64)

currentIngressFlows
optional

Current incomming connections

integer (int64)

currentMessagesSpooled
optional

Current number of messages spooled

integer (int64)

currentQueues
optional

Current number of queues

integer (int64)

currentQueuesAndTopics
optional

Current number of queues and topics

integer (int64)

currentSpoolUsage
optional

Current spool usage in bytes (binary)

integer (int64)

currentTopics
optional

Current number of topics

integer (int64)

currentTransactedSessions
optional

Current number of transacted sessions

integer (int64)

currentTransactions
optional

Current amount of transactions

integer (int64)

egressThreshold
optional

Egress thresholds for client events

ResourceThreshold

ingressThreshold
optional

Ingress thresholds for client events

ResourceThreshold

maximumEgressFlows
optional

Maximum number of outgoing connections

integer (int64)

maximumIngressFlows
optional

Maximum number of incomming connections

integer (int64)

maximumQueuesAndTopics
optional

Maximum number of queues and topics

integer (int64)

maximumSpoolUsage
optional

Maximum spool usage in bytes (binary)

integer (int64)

maximumTransactedSessions
optional

Maximum number of transacted sessions

integer (int64)

maximumTransactions
optional

Maximum number of transactions

integer (int64)

queueAndTopicThreshold
optional

Queue and topic thresholds for client events

ResourceThreshold

spoolThreshold
optional

Spool usage thresholds for client events

ResourceThreshold

transactedSessionThreshold
optional

Transacted session thresholds for client events

ResourceThreshold

transactionThreshold
optional

Transaction thresholds for client events

ResourceThreshold

3.7. Statistics

Statistics for the broker resource.
Supported plan: dedicated

Name Description Schema

connections
optional

Number of connections

integer (int64)

maxSizeInBytes
optional

The maximum size of all messages (in bytes)

integer (int64)

size
optional

The current ammount of messages spooled

integer (int64)

sizeInBytes
optional

The current size of all messages (in bytes)

integer (int64)