Publish / Subscribe

Publish / Subscribe

This tutorial will introduce you to the fundamentals of the Solace REST messaging API. The tutorial will show you how to connecting a client, sending a message on a topic subscription and receive this message again through the Solace REST messaging API. This forms the basis for any publish / subscribe message exchange illustrated here:

Assumptions

This tutorial assumes the following:

  • You are familiar with Solace core concepts.
  • You have access to a running Solace message router with the following configuration:
    • Connectivity information for a Solace message-VPN
    • Enabled client username and password
    • Enabled guaranteed messaging support (needed for REST consumers)
    • Client-profile enabled with guaranteed messaging permissions.
  • REST service enabled for incoming and outgoing messages

One simple way to get access to Solace messaging quickly is to create a messaging service in Solace Cloud as outlined here. You can find other ways to get access to Solace messaging below.

You can learn all about REST on Solace messaging by referring to the Online REST Messaging Documentation.

Goals

The goal of this tutorial is to demonstrate the most basic messaging interaction using Solace. This tutorial will show you:

  1. How to send a message on a topic using the Solace REST messaging API
  2. How to receive a message using the Solace REST messaging API

Solace REST Messaging API Introduction

As outlined in the Online REST Messaging Documentation, the API enable users to send messages to and asynchronously receive messages with Solace messaging over HTTP using a RESTful API.

The Solace API uses the HTTP POST requests to allow clients to publish message Solace messaging. On the subscribe side, the Solace API follows the asynchronous notification pattern and use an HTTP POST from Solace messaging to the client to delivery messages. This means that pub and sub messages are sent on different HTTP connections than they are received as shown in the following figure.

solace-rest-messaging-api

There are several benefits to this approach. First it removes the possibility of message loss which can exist when using HTTP GET requests without explicate separate acknowledgement.. It also enables much higher performance and overall message rate when multiple, parallel HTTP connections are used.

The Online REST Messaging Documentation has the following parts which explain the API in more detail:

  • REST Messaging Introduction & REST Messaging Concepts which explains the API at an architectural level.
  • REST Messaging Protocol which explains the wireline details explains like how to format the HTTP messages etc.

Because of the difference between publishing and subscribing, these topics are introduced as needed in the tutorial below.

Get Solace Messaging

This tutorial requires access Solace messaging and requires that you know several connectivity properties about your Solace messaging. Specifically you need to know the following:

Resource Value Description
Host String This is the address clients use when connecting to the Solace messaging to send and receive messages. (Format: DNS_NAME:Port or IP:Port)
Message VPN String The Solace message router Message VPN that this client should connect to.
Client Username String The client username. (See Notes below)
Client Password String The client password. (See Notes below)

There are several ways you can get access to Solace Messaging and find these required properties.

Option 1: Use Solace Cloud

  • Follow these instructions to quickly spin up a cloud-based Solace messaging service for your applications.
  • The messaging connectivity information is found in the service details in the connectivity tab (shown below). You will need:
    • Host:Port (use the REST URI)
    • Message VPN
    • Client Username
    • Client Password

Option 2: Start a Solace VMR

  • Follow these instructions to start the Solace VMR in leading Clouds, Container Platforms or Hypervisors. The tutorials outline where to download and how to install the Solace VMR.
  • The messaging connectivity information are the following:
    • Host: <public_ip> (IP address assigned to the VMR in tutorial instructions)
    • Message VPN: default
    • Client Username: sampleUser (can be any value)
    • Client Password: samplePassword (can be any value)

    Note: By default, the Solace VMR “default” message VPN has authentication disabled.

Option 3: Get access to a Solace appliance

  • Contact your Solace appliance administrators and obtain the following:
    • A Solace Message-VPN where you can produce and consume direct and persistent messages
    • The host name or IP address of the Solace appliance hosting your Message-VPN
    • A username and password to access the Solace appliance

Obtaining the Solace API

There is no API to obtain. The Solace REST messaging API is a wireline RESTful HTTP protocol. It is fully outlined in REST Messaging Protocol.

Receiving a message

First this tutorial will show how to setup the subscriber side so that you are ready to receive messages that are published.

On the consume side, the Solace REST messaging API depends on a guaranteed messaging queue. As such it is a requirement for REST consumers that Solace messaging support guaranteed messaging and have this feature configured as outlined in the assumptions section above.

In order to receive REST messages from Solace messaging, you must configure a Guaranteed messaging queue and a REST delivery point. The queue is used to attract messages to the consumer application. The REST delivery point is the Solace message router component that delivers the messages from the queue to the consumer application asynchronously through HTTP POST requests. This is explained in more detail in the REST Messaging Concepts where the REST consumers are explained. This tutorial will walk you through the required Solace messaging configuration steps required to create a queue and REST delivery point to connect to your REST consumer application.

A Simple REST Consumer

First you need a REST consuming application ready to receive HTTP connections from Solace messaging. This can be any HTTP server. This tutorial will demonstrate this using Node.js but Solace REST Messaging uses standard HTTP, so use your favorite HTTP server.

Create a file named NodeRestServer.js with the following contents.

var http = require('http');

http.createServer(function (req, res) {
    console.log('Received message: ' + req.url);
    res.writeHead(200);
    res.end();
}).listen(RC_PORT, 'RC_HOST');
console.log('Server running at http://RC_HOST:RC_PORT/');

In the above, you need to update RC_HOST and RC_PORT to represent the HOST and PORT that your REST consumer application will be listening on. This HTTP server listens for incoming requests and for each request it will print the URL of the request and respond with a 200 OK response. The 200 OK response indicates to Solace messaging that the message has been successfully processed and it can be removed from Solace messaging queue.

Start your REST consumer using Node.js. For example:

$ node NodeRestServer.js
Server running at http://RC_HOST:RC_PORT/

Note: The executable is nodejs on Ubuntu due to a naming conflict with other packages.

Again in your environment, the RC_HOST and RC_PORT will be the host/IP and port that your server is listening on. For example http://192.168.1.110:9090/.

Note: Even though this tutorial is illustrating how to publish with direct messages, for REST delivery points, the messages are always consumed from a queue. The incoming messages are promoted into the Solace queue as non-persistent messages and delivered to the REST consumer as non-persistent messages. For more information on this see the Features – Topic Matching and Message Delivery Modes.

Configuring a REST Delivery Point

Next, you must configure a queue and REST delivery point on Solace messaging. This means configuring the following Solace messaging components.

Resource Value
Queue Q/rdp1/input
Pub/Sub Topic T/rest/pubsub
REST Delivery Point rdp1
Queue Binding Q/rdp1
POST Request Target /rest/tutorials
REST Consumer rc1
Remote Host RC_HOST – Update to match REST consumer application.
Remote Port RC_PORT – Update to match REST consumer application.

You can learn about each of these components using Features – REST Introduction. In the script below, update VPNNAME to match that of your Solace messaging solution, and the RC_HOST and RC_PORT to match your REST consumer application.

home
enable
configure

message-spool message-vpn "VPNNAME"
    ! pragma:interpreter:ignore-already-exists
    create queue "Q/rdp1/input" primary
        access-type "exclusive"
        permission all "delete"
        subscription topic "T/rest/pubsub"
        no shutdown
        exit
    exit

message-vpn "VPNNAME"
    rest
        ! pragma:interpreter:ignore-already-exists
        create rest-delivery-point "rdp1"
            shutdown
            client-profile "default"
            ! pragma:interpreter:ignore-already-exists
            create queue-binding "Q/rdp1/input"
                post-request-target "/rest/tutorials"
                    exit
            ! pragma:interpreter:ignore-already-exists
            create rest-consumer "rc1"
                shutdown
                remote host "RC_HOST"
                remote port "RC_PORT"
                no shutdown
                exit
            no shutdown
            exit
        exit
    exit
end

To apply this configuration, simply log in to Solace messaging CLI as an admin user and paste the above script fragments into the CLI.

If using a VMR load, log in to the Solace message router CLI using the management username and password for your Solace VMR.

ssh admin@<HOST>
Solace - Virtual Message Router (VMR)
Password:

At this the REST delivery point is configured and should be operational and connected to your REST consumer application. You can verify this using SolAdmin or through the following CLI command.

solace(configure)# show message-vpn VPNNAME rest rest-delivery-point *

Total REST Delivery Points (up):                       1
Total REST Delivery Points (configured):               1
Total REST Consumers (up):                             1
Total REST Consumers (configured):                     1
Total REST Consumer Outgoing Connections (up):         3
Total REST Consumer Outgoing Connections (configured): 3
Total Queue Bindings (up):                             1
Total Queue Bindings (configured):                     1

Flags Legend:
A - Admin State (U=Up, D=Down)
O - Oper State (U=Up, D=Down)

                                                  REST
                                                Consumer
                                                Outgoing      Queue       Conns
                                        Status    Conns      Bindings    Blocked

RDP Name             Message VPN         A O    (up/conf)    (up/conf)     (%)
-------------------- ------------------ ------ ----------- ------------- -------
rdp1                 default             U U       3 / 3       1 / 1        0

At this point the consumer is up and ready to receive messages.

Sending a message

Now it is time to send a message to the waiting consumer.

Sending a REST message to Solace is very simple. For this example, we will use the command line tool cURL to send the required HTTP. Refer to REST Messaging Protocol Guide for the full details of the Solace REST messaging API.

To send a message you can use the following command.

$ curl -X POST -d "Hello World REST" http://HOST:PORT/T/rest/pubsub -H "content-type: text" -H "Solace-delivery-mode: direct"

You will need to update HOST and PORT to match your Solace messaging HOST and REST service port. This will send a message with contents “Hello World REST” as a Solace text message using the direct delivery mode. The “content-type” headers and “Solace-delivery-mode” are optional. If they are omitted then the Solace REST messaging default delivery mode of “persistent” will be used and the message contents will be treated as binary.

You can also add credentials to the request by updating the cURL command to the following:

$ curl -X POST -d "Hello World REST" http://HOST:PORT/T/rest/pubsub -H "content-type: text" -H "Solace-delivery-mode: direct" --user restUsers:restPassword

At this point your REST consumer should have received a message. It will print the URL to the screen. So the output should now include:

Received message: /rest/tutorials

Summarizing

You have now successfully sent and received a REST message on a topic.

If you have any issues sending and receiving a message, check the Solace community for answers to common issues.