3 Accessing Oracle Messaging Cloud Service Using REST API
Topics:
Topology API
The topology API provides functionality to obtain the topology of a namespace or messaging context. The topology API is available only through the REST API. The information provided by the topology API will, in general, reflect the most recent topology of a namespace or messaging context, but is not necessarily real-time. That is, changes to a namespace or messaging context that has just happened may not be reflected immediately.
Topics:
Viewing all Messaging Contexts
A user can view all messaging contexts and their encapsulated ephemeral resources.
Method: GET
Path: /messagingcontexts
Scope: Service Instance
Authorization: Messaging Administrator or Messaging Worker
Result: Returns the topology information of all messaging contexts and their encapsulated ephemeral resources.
Response Body: JSON or XML.
JSON
The JSON output for a GET from /messagingcontexts is a JSON array. Each element of the array is a JSON object corresponding to a single, unique messaging context.
JSON Object for a Messaging Context
A JSON object for a messaging context will contain at most the following fields:
| Field Name | Description |
|---|---|
|
|
A service-generated ID for the messaging context. This ID is relevant only to the topology API. Each element of the array will have a different |
|
|
A JSON array of JSON objects, with each element representing a distinct connection created in the messaging context. If there are no unclosed connections in the messaging context, this field will not be present. |
JSON Object for a Connection
A JSON object for a connection will contain at most the following fields:
| Field Name | Description |
|---|---|
|
|
The name under which the REST API client created the connection. This field is always present. |
|
|
The connection’s client ID; if the connection does not have a client ID, this field will not be present. |
|
|
A boolean that is |
|
|
A JSON array of JSON objects, with each element representing a distinct session created from this connection. If there are no unclosed sessions currently created from this connection, this field will not be present. |
|
|
A JSON array of JSON objects, with each element representing a temporary queue associated with this connection. If there are no undeleted temporary queues associated with this connection, this field will not be present. |
|
|
A JSON array of JSON objects, with each element representing a temporary topic associated with this connection. If there are no temporary topics associated with this connection, this field will not be present. |
JSON Object for a Session
A JSON object for a session will contain at most the following fields:
| Field Name | Description |
|---|---|
|
|
The name under which the REST API client created the session. This field is always present. |
|
|
A boolean that is |
|
|
A boolean indicating the acknowledgement mode of the session. Its value is |
|
|
A JSON array of JSON objects, with each element representing a distinct session created from this connection. If there are no unclosed sessions currently created from this connection, this field will not be present. |
|
|
A JSON array of JSON objects, with each element representing a producer in this session. If there are no unclosed producers in this session, this field will not be present. |
|
|
A JSON array of JSON objects, with each element representing a consumer in this session. If there are no unclosed consumers in this session (other than durable subscribers), this field will not be present. Consumers that are durable subscribers will not appear in this array. |
|
|
A JSON array of JSON objects, with each element representing a durable subscriber in this session. If there are no unclosed durable subscribers in this session, this field will not be present. |
|
|
A JSON array of JSON objects, with each element representing a queue browser in this session. If there are no unclosed queue browsers in this session, this field will not be present. |
JSON Object for a Producer
A JSON object for a producer will contain at most the following fields:
| Field Name | Description |
|---|---|
|
|
The name under which the REST API client created the producer. This field is always present. |
|
|
The destination to which the producer sends messages. If the producer has no associated destination (so that the destination to which a message is sent must be specified in the send), this field will not be present. If present, it will have one of the following formats:
|
|
|
The time-to-live, in milliseconds, that is the default time-to-live for messages sent by this producer. This field will always be present, and will be formatted as an integer, not a String. |
|
|
A String giving the default delivery mode for messages sent by this producer. This field will always be present, and will have the value persistentor non_persistent.
|
JSON Object for a Consumer
A JSON object for a consumer (other than a durable subscriber) will contain at most the following fields:
| Field Name | Description |
|---|---|
|
|
The name under which the REST API client created the consumer. This field is always present. |
|
|
The destination from which the producer receives messages. This field will always be present, and will have one of the following formats:
|
|
|
The selector for the consumer. This field will only be present if the consumer has a selector. |
|
|
The local mode of the consumer, which defines whether a consumer on a topic will receive message sent on the same connection the consumer was created from. If the consumer is not on a topic or temporary topic, this field will not be present. The default is for topic consumers to receive all messages sent to the topic that match their selector, so this field will only be present if the consumer does not receive messages sent on its connection, in which case the field will be present, and will have value |
JSON Object for a Durable Subscriber
A JSON object for a durable subscriber will contain at most the following fields:
| Field Name | Description |
|---|---|
|
|
The name under which the REST API client created the consumer. This field is always present. |
|
|
The destination from which the producer receives messages. This field will always be present, and will have one of the following formats:
|
|
|
The string that is the subscription name corresponding to the subscriber. Note: This is different from the |
|
|
The selector for the consumer. This field will only be present if the consumer has a selector. |
|
|
The local mode of the consumer, which defines whether a consumer on a topic will receive message sent on the same connection the consumer was created from. If the consumer is not on a topic or temporary topic, this field will not be present. The default is for topic consumers to receive all messages sent to the topic that match their selector, so this field will only be present if the consumer does not receive messages sent on its connection, in which case the field will be present, and will have value |
JSON Object for a Queue Browser
A JSON object for a queue browser will contain at most the following fields:
| Field Name | Description |
|---|---|
|
|
The name under which the REST API client created the queue browser. This field is always present. |
|
|
The queue that the browser browses. This field is always present, and will have the format |
|
|
The selector for the browser. This field will only be present if the browser has a selector. |
XML
The XML output for a GET from /messagingcontexts is an XML document with root element <messagingcontexts>. The XML output for a given service instance is closely analogous to the JSON in the following sense:
-
A field in JSON object with a certain name will be represented in XML by a child element whose name is the same as the field name, and whose content corresponds to that of the value of the field.
-
The elements of a JSON array will be represented in XML as a sequence of
<items>elements, with the content of the nth<items>corresponding to the nth value in the JSON array.
Viewing a Messaging Context
A user can view a single messaging context and all of its encapsulated ephemeral resources by providing the messaging context's ID
Method: GET
Path: /messagingcontexts/messagingContextID
Scope: Messaging Context
Authorization: Messaging Administrator or Messaging Worker
Result: Returns the topology information of a single messaging context and all of its encapsulated ephemeral resources.
Response Body: JSON or XML.
JSON
The output for a GET from /messagingcontexts/messagingContextID is a JSON object that represents the messaging context with the specified ID. The output format is same as described in the JSON output sections for messaging contexts. A 404 response is generated if the service instance has no messaging context with the given ID.
XML
The XML output for a GET from /messagingcontexts/messagingContextID is an XML document with root element <messagingcontexts> whose content is XML corresponding to the fields of a JSON object representing the messaging context with the specific ID. A 404 response is generated if the service instance has no messaging context with the given ID.
Sample Outputs of Topology API
This section provides sample outputs of the topology API.
Sample JSON Output
GET /messagingcontexts for a service instance with two messaging contexts:[
{
"id":"19CB3BA96A0B068B"
},
{
"id":"7E1B3AAF09D27170",
"connections":[
{
"name":"conn348755961301170266",
"clientId":"topologyCID2211817070735200489",
"started":true,
"sessions":[
{
"name":"topologySession6782049576740617368",
"transacted":true,
"consumers":[
{
"name":"cons1986478156341504515",
"destination":"/topics/topologyTopic1",
"selector":"property195=232"
},
{
"name":"cons8406813156667706998",
"destination":"/topics/topologyTopic2",
"localMode":"NO_LOCAL"
}
],
"durableSubscribers":[
{
"name":"sub8114000992284070555",
"destination":"/topics/topologyTopic2",
"subscriptionName":"subscr668",
"localMode":"NO_LOCAL"
},
{
"name":"sub8218579099988865396",
"destination":"/topics/topologyTopic1",
"subscriptionName":"subscr819"
}
],
"queueBrowsers":[
{
"name":"qb658303539525244693",
"queue":"/queues/topologyQueue1",
"selector":"property499=195"
},
{
"name":"qb7987305899602893098",
"queue":"/queues/topologyQueue2",
"selector":"property269=410"
}
]
},
{
"name":"topologySession4005620455377307315",
"transacted":false,
"ackMode":"auto",
"producers":[
{
"name":"prod2624315421281685702",
"destination":"/queues/topologyQueue1",
"timeToLive":1209600000,
"deliveryMode":"non_persistent",
}
],
"durableSubscribers":[
{
"name":"sub1542678913898814730",
"destination":"/topics/topologyTopic1",
"subscriptionName":"subscr765"
}
],
"queueBrowsers":[
{
"name":"qb8302598228704858736",
"queue":"/queues/topologyQueue0"
},
{
"name":"qb4326110554531990221",
"queue":"/queues/topologyQueue3",
"selector":"property197=858"
}
]
}
],
"temporaryQueues":[
{
"name":"68BC612EB343DB9A"
}
],
"temporaryTopics":[
{
"name":"D1970C11C263F97D"
}
]
}
]
}
]
The JSON output of GET /messagingcontexts/19CB3BA96A0B068B for this service instance would therefore be:
{
“id”:"19CB3BA96A0B068B"
}
Sample XML Output
GET /messagingcontexts in the same service instance as above:<messagingcontexts>
<items>
<id>19CB3BA96A0B068B</id>
</items>
<items>
<id>7E1B3AAF09D27170</id>
<connections>
<items>
<name>conn348755961301170266</name>
<clientId>topologyCID2211817070735200489</clientId>
<started>true</started>
<sessions>
<items>
<name>topologySession6782049576740617368</name>
<transacted>true</transacted>
<consumers>
<items>
<name>cons1986478156341504515</name>
<destination>/topics/topologyTopic1</destination>
<selector>property195=232</selector>
</items>
<items>
<name>cons8406813156667706998</name>
<destination>/topics/topologyTopic2</destination>
<localMode>NO_LOCAL</localMode>
</items>
</consumers>
<durableSubscribers>
<items>
<name>sub8114000992284070555</name>
<destination>/topics/topologyTopic2</destination>
<subscriptionName>subscr668</subscriptionName>
<localMode>NO_LOCAL</localMode>
</items>
<items>
<name>sub8218579099988865396</name>
<destination>/topics/topologyTopic1</destination>
<subscriptionName>subscr819</subscriptionName>
</items>
</durableSubscribers>
<queueBrowsers>
<items>
<name>qb658303539525244693</name>
<queue>/queues/topologyQueue1</queue>
<selector>property499=195</selector>
</items>
<items>
<name>qb7987305899602893098</name>
<queue>/queues/topologyQueue2</queue>
<selector>property269=410</selector>
</items>
</queueBrowsers>
</items>
<items>
<name>topologySession4005620455377307315</name>
<transacted>false</transacted>
<ackMode>auto</ackMode>
<producers>
<items>
<name>prod2624315421281685702</name>
<destination>/queues/topologyQueue1</destination>
<timeToLive>1209600000</timeToLive>
<deliveryMode>non_persistent</deliveryMode>
</items>
</producers>
<durableSubscribers>
<items>
<name>sub1542678913898814730</name>
<destination>/topics/topologyTopic1</destination>
<subscriptionName>subscr765</subscriptionName>
</items>
</durableSubscribers>
<queueBrowsers>
<items>
<name>qb8302598228704858736</name>
<queue>/queues/topologyQueue0</queue>
</items>
<items>
<name>qb4326110554531990221</name>
<queue>/queues/topologyQueue3</queue>
<selector>property197=858</selector>
</items>
</queueBrowsers>
</items>
</sessions>
<temporaryQueues>
<items>
<name>68BC612EB343DB9A</name>
</items>
</temporaryQueues>
<temporaryTopics>
<items>
<name>D1970C11C263F97D</name>
</items>
</temporaryTopics>
</items>
</connections>
</items>
</messagingcontexts>The XML output of GET /messagingcontexts/19CB3BA96A0B068B for this service instance would therefore be:
<messagingcontext> <id>19CB3BA96A0B068B</id> </messagingcontext>
Usage API
The Usage API is a part of the Oracle Messaging Cloud Service REST API that provides information about resource usage for a given Oracle Messaging Cloud Service instance. The API provides information on both how much of certain resources are being used, and on various limits how much those resources may be used.
Topics:
About Usage API
This topic provides information about usage API.
Method: GET
Path: /usage
Scope: Service Instance
Authorization: Messaging Administrator
Response Body: An XML or JSON representation of resource usage and limits. The format is chosen based on the value of the Accept header.
-
How many connections, queues, topics, and durable subscriptions are currently being used, and what are the maximum numbers of each that can be used for the given service instance.
-
The hard and soft quotas on destination backlogs. Note that the API returns only the quotas, not the backlog sizes. For more information, see Hard and Soft Quotas
-
Metering data: How many bytes of data have been sent out through the REST API (the egress data) and the number of calls to the REST API in a particular period of time. The egress data includes all bytes sent in HTTP responses, including status line, headers, and the response body. The number of calls to the REST API includes all HTTP requests made.
The information provided by the usage API will, in general, reflect the most recent usage, but is not necessarily real-time. That is, changes to resource usage, metering data, etc. that have just happened may not be reflected immediately.
The Usage API returns usage information for connections, queues, topics, and durable subscriptions, and hard and soft quota limits for destination backlogs. The Usage API also returns the most recent metering data which contains both the number of API calls and egress bandwidth. The non-metered data is accurate to the last 30 seconds. The metered data, api calls and egress bandwidth, are an aggregate over a time period and each metered data section contains the respective start and end times for the metered data. The metered data start and end times are in Coordinated Universal Time (UTC). The destination backlog data is limited to returning the hard quota and soft quota which applies to all destinations (queues and topics) for a service. The backlog quotas apply to both the number of messages and total bytes of messages. If the hard quota of either is exceeded, then sends will fail until the backlog falls below the soft quota.
JSON Format
Usage information in JSON is expressed as a JSON object. The connection, queue, topic, and durable subscription usage is given by the "connectionCount", "queueCount", "topicCount", and "durableSubscriptionCount" fields of the object respectively. The value of each of these fields is a JSON object with a "max" field whose value is the maximum number of connections, queues, topics, or durable subscriptions that may be used, and a "used" field whose value is the current number of connections, queues, topics, or durable subscriptions in use (subject to the above caveats about the data not being real-time).
Destination backlog limitations on number and number of bytes of messages are given by the "destinationBacklogMessageCount" and "destinationBacklogBytes" fields respectively. The value of each of these fields is a JSON object with a "hardQuota" field whose value is the hard quota and a "softQuota" field whose value is the soft quota.
Metering data is given by a "meteringUsages" field whose value is a JSON array of JSON objects. Each object in the array contains the metering data for a certain time period, expressed as the following fields:
-
"startTimeUtc"The value of this field is the first minute of the time period for the metering data, expressed in Coordinated Universal Time (UTC).
-
"endTimeUtc"The value of this field is the last minute of the time period for the metering data, expressed in Coordinated Universal Time (UTC). The metering data will include all metering for the entire minute. For example, if the end time is
2015-07-09T13:09, all API calls occurring at or after 13:09 but before 13:10 will be included. -
"dataCenter"The value of this field is the data center to which the metering data in the element applies.
-
"meteredResourceUsages"A JSON array of JSON objects containing data on a given metered resource for the given period and data center.
Each object in the
"meteredResourceUsages"array will have the following fields:-
"resourceName"The value of this field is the name of the resource whose data is being reported. The value of this field will be either
"EGRESS_DATA"or"API_CALLS". -
"quantity"The value of this field is an integer giving amount of the resource used.
-
"units"The value of this field is the unit of measurement for the value of the
"quantity"field. If the value of"resourceName"is"EGRESS_DATA", the value of"units"will be"Bytes". If the value of"resourceName"is"API_CALLS", the value of"units"will be"API Calls".
-
XML Format
The connection, queue, topic, and durable subscription usage is given by the <connectionCount>, <queueCount>, <topicCount>, and <durableSubscriptionCount> elements respectively. Each of these elements contains a <max> element whose content is the maximum number of connections, queues, topics, or durable subscriptions that may be used, and a <used> element whose content is the current number of connections, queues, topics, or durable subscriptions in use (subject to the above caveats about the data not being real-time).
Destination backlog limitations on number and number of bytes of messages are given by the <destinationBacklogMessageCount> and <destinationBacklogBytes> elements respectively. Each of these elements contains a <hardQuota> element whose content is the hard quota and a <softQuota> element whose content is the soft quota.
Metering data is contained in <meteringUsages> elements. Each such element contains the metering data for a certain time period, expressed as the following child elements:
-
<startTimeUtc>The content of this element is the first minute of the time period for the metering data, expressed in Coordinated Universal Time (UTC).
-
<endTimeUtc>The content of this element is the last minute of the time period for the metering data, expressed in Coordinated Universal Time (UTC). The metering data will include all metering for the entire minute. For example, if the end time is
2015-07-09T13:09, all API calls occurring at or after 13:09 but before 13:10 will be included. -
<dataCenter>The content of this element is the data center to which the metering data in the element applies.
-
<meteredResourceUsages>One or more elements containing data on a given metered resource for the given period and data center.
Each
<meteredResourceUsages>element will contain the following elements:-
<resourceName>The content of this element is the name of the resource whose data is being reported. The content of this element will be either
EGRESS_DATAorAPI_CALLS. -
<quantity>The content of this element is an integer giving amount of the resource used.
-
<units>The content of this element is the unit of measurement for the content of the
<quantity>element. If the content of<resourceName>isEGRESS_DATA, the content of<units>will beBytes. If the content of<resourceName>isAPI_CALLS, the content of<units>will beAPI Calls.
-
Sample Outputs of Usage API
This section provides sample outputs of the usage API.
Sample JSON Output
Sample JSON output of the usage API:
{
"connectionCount": {
"max": 200,
"used": 3
},
"queueCount": {
"max": 10000,
"used": 156
},
"topicCount": {
"max": 10000,
"used": 156
},
"durableSubscriptionCount": {
"max": 10000,
"used": 53
},
"destinationBacklogMessageCount": {
"hardQuota": 100,
"softQuota": 70
},
"destinationBacklogBytes": {
"hardQuota ": 52428800,
"softQuota ": 36700160
},
"meteredUsages": [
{
"dataCenter": "dc",
"endTimeUtc": "2015-07-09T13:09",
"meteredResourceUsages": [
{
"quantity": 2425581,
"resourceName": "EGRESS_DATA",
"units": "Bytes"
},
{
"quantity": 3426,
"resourceName": "API_CALLS",
"units": "API Calls"
}
],
"startTimeUtc": "2015-07-09T13:00"
},
{
"dataCenter": "dc",
"endTimeUtc": "2015-07-09T13:19",
"meteredResourceUsages": [
{
"quantity": 2425521,
"resourceName": "EGRESS_DATA",
"units": "Bytes"
},
{
"quantity": 3426,
"resourceName": "API_CALLS",
"units": "API Calls"
}
],
"startTimeUtc": "2015-07-09T13:10"
}
]
}Sample XML Output
Sample XML output of the usage API:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<usage>
<connectionCount>
<max>200</max>
<used>3</used>
</connectionCount>
<queueCount>
<max>10000</max>
<used>156</used>
</queueCount>
<topicCount>
<max>10000</max>
<used>156</used>
</topicCount>
<durableSubscriptionCount>
<max>10000</max>
<used>53</used>
</durableSubscriptionCount>
<destinationBacklogMessageCount>
<hardQuota>100</hardQuota>
<softQuota>70</softQuota>
</destinationBacklogMessageCount>
<destinationBacklogBytes>
<hardQuota>52428800</hardQuota>
<softQuota>36700160</softQuota>
</destinationBacklogBytes>
<meteredUsages>
<startTimeUtc>2015-07-09T13:00</startTimeUtc>
<endTimeUtc>2015-07-09T13:09</endTimeUtc>
<dataCenter>dc</dataCenter>
<meteredResourceUsages>
<resourceName>EGRESS_DATA</resourceName>
<quantity>2425581</quantity>
<units>Bytes</units>
</meteredResourceUsages>
<meteredResourceUsages>
<resourceName>API_CALLS</resourceName>
<quantity>3426</quantity>
<units>API Calls</units>
</meteredResourceUsages>
</meteredUsages>
<meteredUsages>
<startTimeUtc>2015-07-09T13:10</startTimeUtc>
<endTimeUtc>2015-07-09T13:19</endTimeUtc>
<dataCenter>dc</dataCenter>
<meteredResourceUsages>
<resourceName>EGRESS_DATA</resourceName>
<quantity>2425521</quantity>
<units>Bytes</units>
</meteredResourceUsages>
<meteredResourceUsages>
<resourceName>API_CALLS</resourceName>
<quantity>3426</quantity>
<units>API Calls</units>
</meteredResourceUsages>
</meteredUsages>
</usage>About Escaped Value Strings
This topic provides information about escaped value Strings.
An escaped value String is a String that uses the following JSON conventions for representing characters that may not legally occur in HTTP header values:
| Escape Sequence | Description |
|---|---|
\\ |
The backslash character (\) |
\b |
The backspace character (ctrl-H) |
\f |
The form-feed character (ctrl-L) |
\n |
The new-line character (ctrl-J) |
\r |
The carriage return character (ctrl-M) |
\t |
The tab character |
\u<4 hexadecimal digits> |
The Unicode character whose encoding as an unsigned base-16 integer is given by the 4 hexadecimal digits. |
The following is an example:
| Raw String | Corresponding Escaped Value String |
|---|---|
|
|
Note that if a String s is a legal HTTP header value that contains no backslashes, the escaped value String corresponding to s is the same as s.