REST API for Oracle Messaging Cloud Service

All REST Endpoints

Connections

Connections are necessary to send and receive messages between clients and Oracle Messaging Cloud Service. A connection is the starting point for the resources needed for direct communication between clients and the messaging platform.

A client usually uses one connection for all of its sending and receiving operations, though a client can use multiple connections if desired. Each instance of Oracle Messaging Cloud Service has a quota of concurrently used connections. When an instance is using 100% of its connection quota, additional attempts to create new connections will fail.

A new connection is used in the following situations:

A connection is created through the REST API
A JMS connection is created through the Java library
A message push listener is created

Create a Connection: Method: put
Path: /connections/{connectionName}
Delete a Connection: Method: delete
Path: /connections/{connectionName}
Update Connection Properties: Method: post
Path: /connections/{connectionName}

Durable Subscriptions

Returns information about one or more durable subscriptions depending on the request parameters supplied.

List Durable Subscriptions: Method: get
Path: /subscriptions

Listeners

Message Push Listeners (MPLs) are user-created resources that reside within an Oracle Messaging Cloud Service instance. An MPL asynchronously receives messages from a queue, topic, or durable subscription and either sends the messages to another destination or pushes them to a user-defined URL as an HTTP request.

Create a Listener: Method: put
Path: /listeners/{listenerName}
Delete a Listener: Method: delete
Path: /listeners/{listenerName}
Get Listener Properties: Method: get
Path: /listeners/{listenerName}
List Listeners: Method: get
Path: /listeners

Messaging Contexts

A messaging context is a container of ephemeral objects like connections, sessions, producers, consumers, temporary destinations, and queue browsers.

A messaging context is identified by the JSESSIONID cookie. The only API specific to a messaging context is the API for getting and setting the maximum inactive interval (MII), which controls the expiration time of the messaging context. When the messaging context expires, all ephemeral objects contained in it are closed and deleted, except temporary destinations created in another messaging context. A temporary destination is closed only if the connection by which the temporary destination was created is closed.

Creation of a messaging context is an implicit operation. It is created by the first access to the Oracle Messaging Cloud Service that passes authentication.

Get Maximum Inactive Interval: Method: get
Path: /maxInactiveInterval
Set Maximum Inactive Interval: Method: post
Path: /maxInactiveInterval

Queue Browsers

Queue browsers are used to look at messages on a queue without removing them. A queue browser is created from a session.

A queue browser may be used to look at all the messages in a queue, or only those that match a message selector. Note that if messages are sent to a queue after a browser on that queue is created, those messages may not be visible via the queue browser.

Browse Messages: Method: post
Path: /queueBrowsers/{browserName}
Create a Queue Browser: Method: put
Path: /queueBrowsers/{browserName}
Delete a Queue Browser: Method: delete
Path: /queueBrowsers/{browserName}
Get Queue Browser Properties: Method: get
Path: /queueBrowsers/{browserName}

Queues

Queues are destinations to which messages may be sent that support point-to-point communication.

Create a Queue: Method: put
Path: /queues/{queueName}
Delete a Queue: Method: delete
Path: /queues/{queueName}
Get Queue Properties: Method: get
Path: /queues/{queueName}
List Queues: Method: get
Path: /queues

Receiving Messages

Clients receive messages by using a session to create a consumer. A session can have multiple consumers. Consumers persist until they are closed, or the session in which they were created is closed.

A consumer defines how messages are received from the service. A consumer must specify the destination from which messages are received.

Optionally, consumers can specify a subset of messages to be received by giving a selector. For the syntax of selectors, see the Message Selectors section of the Java API reference for the javax.jms.Message class at the URL: javax.jms.Messageclass.

Create a Consumer: Method: put
Path: /consumers/{consumerName}
Delete a Consumer: Method: delete
Path: /consumers/{consumerName}
Receive a Message: Method: post
Path: /consumers/{consumerName}/messages

Sending Messages

Clients send messages by using a session to create a producer. A session can have multiple producers. Producers persist until they are closed, or the session in which they were created is closed.

A producer defines the default characteristics of messages sent through the producer. A producer can specify the destination to which all messages are sent, how sent messages should be stored in the service, and how long sent messages are stored in the service before they expire.

Create a Producer: Method: put
Path: /producers/{producerName}
Delete a Producer: Method: delete
Path: /producers/{producerName}
Send a Message: Method: post
Path: /producers/{producerName}/messages
Set Properties of a Producer: Method: post
Path: /producers/{producerName}

Sessions

A session must be created before messages can be sent or received. Sessions allow message sends and receives to be grouped into atomic units, undone, or re-done.

A single connection can have multiple sessions. Sessions persist until they are closed, or until the connection from which they were created is closed.

Acknowledge, Commit, Rollback, or Recover a Session: Method: post
Path: /sessions/{sessionName}/state
Create a Session: Method: put
Path: /sessions/{sessionName}
Delete a Durable Subscription: Method: delete
Path: /sessions/{sessionName}/subscriptions/{subscriptionName}
Delete a Session: Method: delete
Path: /sessions/{sessionName}

Temporary Queues

A temporary queue is a queue created for the duration of a connection. Messages may only be consumed from a temporary queue through the connection through which it was created.

Create a Temporary Queue: Method: post
Path: /temporaryQueues
Delete a Temporary Queue: Method: delete
Path: /temporaryQueues/{queueName}
List Temporary Queues: Method: get
Path: /temporaryQueues
Retrieve Properties of a Temporary Queue: Method: get
Path: /temporaryQueues/{queueName}

Temporary Topics

A temporary topic is a topic created for the duration of a connection. Messages may only be consumed from a temporary topic through the connection through which it was created.

Create a Temporary Topic: Method: post
Path: /temporaryTopics
Delete a Temporary Topic: Method: delete
Path: /temporaryTopics/{topicName}
List Temporary Topics: Method: get
Path: /temporaryTopics
Retrieve Properties of a Temporary Topic: Method: get
Path: /temporaryTopics/{topicName}

Topics

Topics are destinations to which messages may be sent that support publish/subscribe, one-to-many communication.

Create a Topic: Method: put
Path: /topics/{topicName}
Delete a Topic: Method: delete
Path: /topics/{topicName}
Get Topic Properties: Method: get
Path: /topics/{topicName}
List Topics: Method: get
Path: /topics

Topology

The Topology API allows a client to see all of the ephemeral objects (messaging contexts, connections, sessions, producers, consumers, queue browsers, and temporary destinations) currently in existence in a service instance.

Retrieve the Topology for all Messaging Contexts: Method: get
Path: /messagingcontexts
Retrieve the Topology of a specific Messaging Context.: Method: get
Path: /messagingcontexts/{messagingContextID}

Usage

The Usage API provides information about how much certain resources are being used by a service instance, and the maximum amount of such resources that the instance is allowed.

An XML or JSON representation of resource usage and limits: Method: get
Path: /usage