Using REST

Representational State Transfer (REST) is a lightweight way of designing network applications. It enables clients and network routers 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 Solace router
  • REST consumers—receives messages from the Solace router

REST Producers

REST producers are applications that send REST messages to a topic or queue within a Message VPN on a Solace router. For REST producers to send messages to a router, they must establish a client connection to the router. The router 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 router 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 Solace routers 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 the Solace messaging platform, REST Consumers REST Delivery Points (RDPs) objects are required. RDPs objects that are provisioned within Message VPNs on the Solace router. Physical REST applications that connect to the router 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 Solace router performs a load balancing function by choosing which REST Consumer to deliver each message to.

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

Note:  Client certificate authentication is only supported for outgoing connections on Solace appliances. It is not supported on Solace VMRs.

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 Solace router. 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 Solace router 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 router.

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 router 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 the Solace platform, 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 router, 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 Solace router will deliver the message to its destination regardless of the message format.

REST Published Message to Solace Router

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

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

REST Producer One-Way POST to Solace Router

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

REST Producer One-Way POST to Solace Router

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

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

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

Solace Router One-Way POST to REST Consumer

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

Solace Router One-Way POST to REST Consumer

In this scenario, the router has received a message, and the router determines that the message will be received by a REST Consumer. If the message type is persistent, the router 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 contained in the message. Upon receiving the message, the REST Consumer acknowledges the message with a POST response of 200 OK to the router.

If the message type was persistent, the router 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 router 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 Solace Router

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 Solace Router

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 Solace router 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 router 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 router 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.

Solace Router Request/Reply to REST Consumer

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

Solace Router Request/Reply to REST Consumer

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

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

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