Using REST Messaging

Representational State Transfer (REST) is a lightweight way of designing network applications. It enables clients and network message brokers to communicate using standard HTTP methods like POST. Systems that implement REST are referred to as RESTful systems. RESTful systems use HTTP methods in a way that is consistent with the HTTP protocol definition (RFC 2616).

REST is not a defined standard but rather a set of guidelines.

REST Producers and Consumers

There are two main actors in the Solace REST protocol:

  • REST producers—sends messages to the message broker
  • REST consumers—receives messages from the message broker

REST Producers

REST producers are applications that send REST messages to a topic or queue within a Message VPN on a message broker. For REST producers to send messages to a message broker, they must establish a client connection to the message broker. The message broker authenticates REST producers when they connect using a basic or client certificate authentication scheme. The Solace REST implementation does not support Kerberos authentication. Clients using a basic authentication scheme can connect as anonymous publishers by not specifying a username or password.

When a connecting REST producers has been authenticated, the privileges for that producer are determined by standard Solace configuration parameters such as client profiles and ACL profiles.

A REST producers that has established a client connection to the message broker is represented as a normal client and will be visible using Solace CLI commands such as the show client User EXEC command.

For information on how message brokers authenticate client entities and the authorization process that is used to provide them with service, refer to Client Authentication/Authorization.

REST Consumers

To consume messages from Solace PubSub+ message broker, REST Consumers REST Delivery Points (RDPs) objects are required. RDPs objects that are provisioned within Message VPNs on the message broker. Physical REST applications that connect to the message broker can bind to an RDP to consume REST messages from it. RDPs consist of the following components:

REST Consumers

REST Consumers are virtual objects within a Message VPN that represent physical consumers of REST messages (that is, client applications).

Each physical consumer that an RDP services is identified by its IP address or hostname and TCP port number. An RDP can service multiple REST consumers. When an RDP services multiple REST Consumers, the message broker performs a load balancing function by choosing which REST Consumer to deliver each message to.

A message broker can be configured to use authentication (basic, client certificate, or none) when it initiates connections to REST Consumers.

Client Profile

An RDP must be assigned an existing client profile in the same Message VPN as the RDP. The RDP uses the TCP parameters and egress queue properties of the bound client profile.

Queue Bindings

An RDP also contains queue bindings, which are references to durable message endpoints on the message broker. RDPs can only be bound to durable queues that exist within the same Message VPN as the RDP.

When an RDP is bound to a queue, messages delivered to that queue will be attracted by the RDP and then scheduled for delivery to one of the REST consumers configured for the RDP.

If a queue is deleted, any queue bindings referencing the deleted queue remain intact but those queue bindings will not be operational. To be brought into service, an RDP must have at least one operational queue binding. An RDP whose queue bindings are all not operational cannot be brought into service.

REST Message Structure

REST messages sent to and from a message broker use the HTTP POST method. The POST structure differs depending on whether the message is a request or a response, and whether the message is being sent to or from a message broker.

The Solace REST interface uses both standard HTTP headers (such as Content-Length) and Solace-specific HTTP headers (such as Solace-Client-Name). HTTP headers that are unique to the Solace REST interface and used internally by the message broker are prefixed by Solace-. To avoid confusion, applications should not use HTTP headers that begin with Solace-. For a complete list of the HTTP headers that are specific to Solace PubSub+, refer to Solace REST Usage of HTTP Headers.

The body of a REST message consists of the data transmitted after the message’s HTTP headers. When a REST message reaches a message broker, this data is encapsulated in a Solace message payload, which may take a number of formats, including text or binary. Messages may optionally omit the message body.

REST Message Structure Examples

The following are some possible configurations of REST messages based on origin and message type.

Note:  There is no requirement for communication between a publisher and a subscriber to be exclusively REST or exclusively non-REST. For example, a REST client can receive a REST message and respond with a Solace Message Format (SMF) message. The message broker will deliver the message to its destination regardless of the message format.

REST Published Message to a Message Broker

A REST message sent from a publisher to a message broker consists of a POST request, HTTP headers, and an HTTP message body. The message broker uses the POST request to determine where to route the message, and the HTTP headers specify message properties that may determine how the message is handled. The body of the POST request is included as the message payload.

REST Message Acknowledgment from a Message Broker

When a message broker successfully receives a REST message, it sends back an acknowledgment (“ack”) in the form of a POST response. For Guaranteed messages, the message broker delays sending the POST response until it successfully spools the message.

An ack consists of a response code (typically 200 OK) and HTTP headers. Because the response code is sufficient to acknowledge receipt of the original message, the returned message has an empty message body.

REST Response from Consumer

If a request/reply exchange pattern is used, when a consumer responds to a REST request message, it reports its own response code (200 OK), new HTTP headers, and a message body. If the response from the consumer is a message, the message body will contain the message payload information that is to be returned to the original publisher.

Message Exchange Patterns

This section describes the common message exchange patterns that may take place when using REST messaging with Solace PubSub+.

REST Producer One-Way POST to a Message Broker

The figure immediately below shows an exchange pattern where a REST producer sends a message to a message broker.

REST Producer One-Way POST to a Message Broker

In this scenario, the REST producer sends a message as a POST request to the message broker by directing the request to a URL that consists of the IP address or hostname of the message broker, the endpoint type (queue or topic), and a queue or topic name. The message broker behaves differently based on whether the message’s delivery mode is identified as direct or persistent.

If the message’s Solace-Delivery-Mode is direct, upon receipt of the message the message broker sends a POST response of 200 OK to the REST producer, then delivers the message. The POST does not indicate that the message has been delivered to its consumers, only that the message broker has received the message.

If the message’s Solace-Delivery-Mode is persistent or non-persistent, when the message broker receives the message it stores it in the message spool, then sends a POST response of 200 OK to the REST producer. Again, the POST response to the REST producer only indicates that the message broker has received the message and does not indicate that the message has been delivered. The message broker then attempts to deliver the message.

A REST producer’s message to a message broker can fail for a number of reasons. If there is an error authenticating the REST Producer with the message broker or if there is an error in the message format, the message broker will return a POST response which includes details of the error.

Message Broker One-Way POST to REST Consumer

The figure immediately below shows a scenario involving a message broker delivering a message to a REST Consumer.

Message Broker One-Way POST to REST Consumer

In this scenario, the message broker has received a message, and the message broker determines that the message will be received by a REST Consumer. If the message type is persistent, the message broker stores the message and retains it until delivery is confirmed.

The message is delivered to the REST Consumer by way of a POST request to a fixed URL (configured in the REST Consumer) that is contained in the message. Upon receiving the message, the REST Consumer acknowledges the message with a POST response of 200 OK to the message broker.

If the message type was persistent, the message broker removes the message from the message spool when a 200 OK response is received. Because this is a one-way message delivery, any information contained in the body of the response from the REST Consumer is discarded.

If the message broker receives any status code in response other than 200 OK, it will continue trying to deliver the message until the delivery is a success or until some other condition is met (for example, the max retry parameter is exceeded).

REST Producer Request/Reply to a Message Broker

The figure immediately below shows how a REST Producer can send a message to any message consumer and specify that a reply message is desired.

REST Producer Request/Reply to a Message Broker

The REST Producer sends an initial REST message that includes the header Solace-Reply-Wait-Time-In-ms. This header indicates that a reply message is expected.

If the message’s Solace-Delivery-Mode is direct, when the message broker receives the message, it encodes the REST message as an SMF message and sends it, with its specified delivery mode, to a consumer. If the message’s Solace-Delivery-Mode is persistent or non-persistent, the message broker spools the message before sending it.

The consumer replies with its own message, which includes a reply to the original message. Upon receiving this reply, the message broker constructs a REST POST response from the reply and delivers it to the original producer with the status code 200 OK and the reply message’s contents as the HTTP message payload.

In this scenario, delivery failure can occur due to a number of reasons, including the wait time being exceeded or the reply message being in an unsupported format.

Message Broker Request/Reply to REST Consumer

The figure immediately below shows how request/reply messages may also originate from a non-REST source.

Message Broker Request/Reply to REST Consumer

This scenario is similar to a one-way POST from a message broker to a REST Consumer. In this case, however, the POST from the message broker that the REST Consumer receives includes a Solace-Reply-Wait-Time-In-ms header. This indicates to the REST Consumer that the message broker expects a reply to the message.

The REST Consumer encodes its reply in the HTTP message body of the POST response that it returns to the message broker. The status code of the response message is 200 OK if the original message was received correctly.

A 200 OK response indicates that the message was received even if, for example, there are errors in processing the message. If required, the REST Consumer can encode details about any errors in the body of a 200 OK response.

REST Producer Request with Asynchronous Reply-to Destination

The figure immediately below shows how an application can send messages and receive asynchronous replies using REST.

REST Producer Request with Async Reply-to Destination

In this scenario, an application acts as both a REST Producer and a REST Consumer (that is, it both sends and receives messages using HTTP POST). As a REST Producer, it sends the message as a POST to the message broker including the Solace-Reply-To-Destination header. The message broker reads the Reply-To information and destination from the POST.

The message broker stores the message on the message spool if it is a persistent message. It then returns a 200 OK status response to the REST Producer before sending the message to the end consumer.

When the end consumer receives the message, the message’s Reply-To information is extracted from the original POST. The consumer sends its reply back to the message broker, where the reply is spooled again.

The message broker delivers the reply message with a POST to the original application, whose connection parameters are stored as a REST Consumer in an RDP on the message broker. When the application receives the final reply message, it sends a 200 OK back to the message broker to indicate that the sequence has completed.