Using REST Messaging

Representational State Transfer (REST) is a lightweight way of designing network applications. It enables clients and network event 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 Concepts

If you haven't used REST and Solace PubSub+ together before, you might want to look at the REST section of Overview: How Apps Interact with PubSub+ Messaging Components. It'll take you on a tour of the PubSub+ event broker's messaging components, and explain at a high level how they make data move from producers to the broker, and from the broker to consumers, with REST.

REST Producers and Consumers

There are two main actors in the Solace REST protocol:

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

REST Producers

REST producers are applications that send REST messages to a topic or queue within a Message VPN on an event broker. For REST producers to send messages to an event broker, they must establish a client connection to the event broker. The event 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 producer has been authenticated, the privileges for that producer are determined by standard Solace configuration parameters, such as client profiles and ACL profiles.

A REST producer that has established a client connection to the event 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 event brokers authenticate client entities and the authorization process that is used to provide them with service, refer to Client Authorization and Client Authentication.

REST Consumers

To consume messages from Solace PubSub+ event broker, REST Consumers REST Delivery Points (RDPs) objects are required. RDPs objects that are provisioned within Message VPNs on the event broker. Physical REST applications that connect to the event 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 event broker performs a load balancing function by choosing which REST Consumer to deliver each message to.

An event 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 event 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 an event 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 an event 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 event 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 an event 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.

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 event broker will deliver the message to its destination regardless of the message format.

REST Published Message to an Event Broker

A REST message sent from a publisher to an event broker consists of a POST request, HTTP headers, and an HTTP message body. The event 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 an Event Broker

When an event broker successfully receives a REST message, it sends back an acknowledgment (“ack”) in the form of a POST response. For Guaranteed messages, the event 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 an Event Broker

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

REST Producer One-Way POST to an Event Broker

In this scenario, the REST producer sends a message as a POST request to the event broker by directing the request to a URL that consists of the IP address or hostname of the event broker, the endpoint type (queue or topic), and a queue or topic name. The event 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 event 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 event broker has received the message.

If the message’s Solace-Delivery-Mode is persistent or non-persistent, when the event 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 event broker has received the message and does not indicate that the message has been delivered. The event broker then attempts to deliver the message.

A REST producer’s message to an event broker can fail for a number of reasons. If there is an error authenticating the REST Producer with the event broker or if there is an error in the message format, the event broker will return a POST response which includes details of the error. The error response you receive depends on the message’s Solace-Delivery-Mode is direct or persistent (or non-persistent). For information about the POST responses, see Solace REST Status Codes.

Event Broker One-Way POST to REST Consumer

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

Event Broker One-Way POST to REST Consumer

In this scenario, the event broker has received a message, and the event broker determines that the message will be received by a REST Consumer. If the message type is persistent, the event 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 event broker.

If the message type was persistent, the event 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 event 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 an Event 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 an Event 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 event 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 event 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 event 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.

Event Broker Request/Reply to REST Consumer

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

Event Broker Request/Reply to REST Consumer

This scenario is similar to a one-way POST from an event broker to a REST Consumer. In this case, however, the POST from the event broker that the REST Consumer receives includes a Solace-Reply-Wait-Time-In-ms header. This indicates to the REST Consumer that the event 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 event 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 event broker including the Solace-Reply-To-Destination header. The event broker reads the Reply-To information and destination from the POST.

The event 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 event broker, where the reply is spooled again.

The event 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 event broker. When the application receives the final reply message, it sends a 200 OK back to the event broker to indicate that the sequence has completed.