Register Now for EDA Summit 2024 - Virtual EventRegister for Free

Publish / Subscribe

14 Minute Read

This tutorial will introduce you to the fundamentals of the Solace REST messaging API. The tutorial will show you how to connect a client, send a message on a topic subscription and receive this message again through the Solace REST messaging API.

Assumptions

This tutorial assumes the following:

  • You are familiar with Solace core concepts.

  • You have access to a running Solace PubSub+ Broker with the following configuration:

    • Connectivity information for a Solace PubSub+ Broker
    • Enabled client username and password
    • Enabled guaranteed messaging support (needed for REST consumers)
    • Client-profile enabled with guaranteed messaging permissions
  • The REST service is enabled and set to Messaging mode, allowing the VPN to act as a message broker

One simple way to get access to Solace messaging systems quickly is to create a messaging service in Solace Cloud as outlined here.

You can learn all about REST on a Solace Message VPN 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 REST Messaging API enable users to send messages to, and asynchronously receive messages from a Solace PubSub+ Broker over HTTP using a RESTful API.

The Solace API uses HTTP POST requests to allow clients to publish message to a Message VPN. The Solace API follows the asynchronous notification pattern and uses an HTTP POST from a Message VPN to the client to deliver messages. This means that pub and sub messages are sent on different HTTP connections than they are received as shown in the following figure.

Diagram: 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 to fetch messages without explicit acknowledgement. It also enables higher performance and overall message rate when multiple, parallel HTTP connections are used.

The Online REST Messaging Documentation 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 - like how to format the HTTP messages etc.,

The REST-based publish and subscribe actions are described in the late part of this tutorial.

Get Solace Messaging

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

Resources Value Description
Host String This is the address clients use when connecting to the PubSub+ messaging to send and receive messages. (Format: DNS_NAME:Port or IP:Port)
Message VPN String The PubSub+ 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 PubSub+ Messaging and find these required properties.

Option 1: Use PubSub+ Cloud

  • Follow these instructions to quickly spin up a cloud-based PubSub+ 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 SMF URI)
    • Message VPN
    • Client Username
    • Client Password
Screenshot: Messaging Connectivity Information

Option 2: Start a PubSub+ Software

  • Follow these instructions to start the PubSub+ Software in leading Clouds, Container Platforms or Hypervisors. The tutorials outline where to download and how to install the PubSub+ Software.

  • 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 PubSub+ Software "default" message VPN has authentication disabled.

Option 3: Get access to a PubSub+ Appliance

  • Contact your PubSub+ appliance administrators and obtain the following:

    • A PubSub+ 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. The details are outlined in REST Messaging Protocol.

Receiving a message

Since Solace PubSub+ is a multi-protocol translation broker, messages can be received using any of the other Solace APIs (e.g., JMS or MQTT) which would be a lot less complicated to use when compared to REST Deliver point based setup.

In this tutorial will show how to setup a subscriber to receive published messages.

Diagram: Receiving a Message

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

In order to receive REST messages from Solace Message VPN, 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 detail in the REST Messaging Concepts. This tutorial will walk you through the required Solace Message VPN configuration 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 Message VPN. This can be any HTTP server. This tutorial will demonstrate this using Node.js HTTP server. 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 + '/');


Note: The values of RC_HOST and RC_PORT need to be updated with the host and port where the REST HTTP server is running. This will be updated as the REST endpoint host and port in the REST Delivery Point configuration.


In the above code, you need to update RC_HOST and RC_PORT to capture 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 Message VPN that the message has been successfully processed, and it can be removed from Solace Message VPN queue.

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

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

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://49.210.148.187 :10000/ or with a public DNS name http://myhost.mydomain.com:10000 (for example).

If running Solace PubSub+ Broker locally, a “localhost” or a local DHCP IP for host name won’t work, since the PubSub+ Broker is usually run on a different subnet. You have to use your computer’s actual (local) IP address.

Note: Even though this tutorial is illustrating how to publish direct messages, for REST delivery points, the messages are always consumed from a queue. Direct messages get promoted in the queue, and are delivered to the REST consumer as Guaranteed 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 a REST delivery point on Solace Message VPN.

Resource Value
Queue Q/rdp1/input
Pub/Sub Topic solace/samples/rest
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.

Update RC_HOST and RC_PORT to capture the HOST and PORT that your REST consumer application will be listening on.

You can learn more about each of these components here - Features – REST Introduction.

In the script below, update VPNNAME to match that of your Solace Message VPN, and the RC_HOST and RC_PORT to match your REST consumer application.

The REST Delivery Point configuration can be affected on a Message VPN in different ways. Here is the list of options available for us.

Option 1: Using PubSub+ Broker Manager
Option 2: Using SEMP and Postman
Option 3: Using SEMP and curl Option 4: Using Solace CLI

Option 1: Using PubSub+ Broker Manager

  • Create a Queue by name Q/rdp1/input

Create queue

Enable both incoming and outgoing configuration

Create queue

Queue successfully created

Create queue

  • Add a Topic Subscription to the queue

Create Queue Subscription

Add a Topic Subscription - solace/samples/rest

Create Queue Subscription

Topic Subscription successfully created

Create Queue Subscription

  • Create a REST Delivery Point object

Create REST Delivery Point

Create a REST Delivery Point - rdp1

Create REST Delivery Point

Configure the REST Delivery Point

Create REST Delivery Point

REST Delivery Point successfully created

Create REST Delivery Point

  • Create a Queue Binding object

Create a queue binding to the queue you created previously. This will tell the RDP where to fetch messages from. Note that REST Delivery Points (RDPs) can be bound to multiple queues.

Create Queue Binding

Create a queue binding - Q/rdp1/input

Create Queue Binding

Set the POST target where the requests would be sent - /rest/tutorials

Create Queue Binding

Note that the RDP is down - it will automatically start up when a REST consumer makes a connection to the RDP.

Create Queue Binding

  • Create a REST Consumer object

Create REST Consumer

Create a REST Consumer - rc1

Create REST Consumer

Enable the REST Consumer and set HOST:PORT details of the message HTTP listener

Create REST Consumer

Note: If you do not have a public IP or DNS name for the host where the consumer is run, you can use ngrok utility to expose the local host:port to be accessible from anywhere.

To use ngrok for this purpose:

  • Download and install ngrok from https://ngrok.com/download

  • Run the ngrok command from the terminal or command window:

    ngrok protocol portnumber

    The first parameter is the protocol and second parameter is the port number on which the local listener is running.

    For example to expose a web server on port 1000 of your local machine to the internet, you can run the following command.

    ngrok http 10000

    Upon start, the ngrok utility will open tunnels for plain and secured connections.

    ngrok command

    Now the local service is available for access from the net via host eb2f-49-205-141-108.ngrok.io and port 80 or 443


REST Consumer successfully created

Create REST Consumer


A final, configured RDP settings would look like this.

RDP Configuration

To know more about PubSub+ Broker Manager check out PubSub+ Broker Manager overview.

Option 2: Using SEMP and Postman

Solace Element Management Protocol version 2 (SEMP v2) is a RESTful API that you can use to configure Solace PubSub+ event brokers. It complements Solace's CLI and PubSub+ Manager, and provides a programmable way to configure Solace PubSub+ event brokers.

  1. Download SEMP v2 specification

Download SEMP v2
Alternately, you can download from the following URLs:

http://<SOFTWARE_BROKER_HOST>:8080/SEMP/v2/config/spec

Where the SOFTWARE_BROKER_HOST is the host name where the Software Broker is running.

or

https://CLOUD_BROKER_HOST:943/SEMP/v2/config/spec

Where the CLOUD_BROKER_HOST is the host name of where the Cloud Broker is running.

  1. Launch postman and import the JSON file

Import SEMP v2

  1. Review the imported API collection

SEMP v2 API Collection

  1. Note the SEMP v2 URL and access credentials

    For PubSub+ Software Broker - the SEMP requests can be posted to the following URL

    http://<SOFTWARE_BROKER_HOST>:8080/SEMP/v2/config

    Where the SOFTWARE_BROKER_HOST is the host name where the Software Broker is running.

    Make a note of the broker name, a CLI/SEMP username (or an admin username) and password that has full access to the broker.

    SEMP - Software Broker

    For PubSub+ Cloud Broker - select the Broker Service, Select the Manage tab and locate the SEMP - REST API section. Note the URL to SEMP spec

    https://CLOUD_BROKER_HOST:943/SEMP/v2/config

    Where the CLOUD_BROKER_HOST is the host name of where the Cloud Broker is running.

    Make a note of the SEMP user credentials listed here.

    SEMP - Cloud Broker


  1. Execute the following SEMP POST requests to create resources associated with REST Delivery Point.
    The following steps demonstrate invoking SEMP REST API against a PubSub+ Cloud Broker as identified by the host CLOUD_BROKER_HOST and a Message VPN identified by VPN_NAME. For PubSub+ Software Broker, use the host on which the software Broker is running.


    Ensure that the REST requests are appropriately updated with user credentials and the APIs are invoked as POST requests.

Create queue


  • Create a Queue object
URL: 
https://CLOUD_BROKER_HOST:943/SEMP/v2/config/msgVpns/VPN_NAME/queues

BODY:
{
  "accessType": "exclusive",
  "egressEnabled": true,
  "ingressEnabled": true,
  "msgVpnName": "VPN_NAME",
  "owner": "all",
  "permission": "consume",
  "queueName": "Q/rdp1/input"
}

Create queue

  • Add a Topic Subscription to the queue
Note: Since the queue name parameter contains '/' character, you have to select the queue name string in the URL and encode the URI component.

Create queue

Create queue

Create queue


URL: 
https://CLOUD_BROKER_HOST:943/SEMP/v2/config/msgVpns/VPN_NAME/queues/Q%2Frdp1%2Finput/subscriptions
BODY:
{
    "msgVpnName": "VPN_NAME",
    "queueName": "Q/rdp1/input",
    "subscriptionTopic": "solace/samples/rest"
}

Create queue

  • Create a REST Delivery Point object
URL: 
https://CLOUD_BROKER_HOST:943/SEMP/v2/config/msgVpns/VPN_NAME/restDeliveryPoints

BODY:
{
    "clientProfileName": "default",
    "enabled": true,
    "msgVpnName": "VPN_NAME",
    "restDeliveryPointName": "rdp1"
}

Create queue

  • Create a Queue Binding object
URL: 
https://CLOUD_BROKER_HOST:943/SEMP/v2/config/msgVpns/VPN_NAME/restDeliveryPoints/rdp1/queueBindings

BODY:
{
    "gatewayReplaceTargetAuthorityEnabled": false,
    "msgVpnName": "VPN_NAME",
    "postRequestTarget": "/rest/tutorials",
    "queueBindingName": "Q/rdp1/input",
    "restDeliveryPointName": "rdp1"
}

Create queue

  • Create a REST Consumer object

Update RC_HOST and RC_PORT to capture the HOST and PORT that your REST consumer application will be listening on along with VPN_NAME with the Message VPN name.

URL: 
https://CLOUD_BROKER_HOST:943/SEMP/v2/config/msgVpns/VPN_NAME/restDeliveryPoints/rdp1/restConsumers

BODY:
{
    "enabled": true,
    "msgVpnName": "VPN_NAME",
    "remoteHost": "RC_HOST",
    "remotePort": RC_PORT,
    "restConsumerName": "rc1",
    "restDeliveryPointName": "rdp1",
    "tlsEnabled": false
}

Create queue


Note: It should be noted that Postman tool offers a UI based API invocation to affect changes on the Broker. Non-UI tools like curl can also be used to accomplish the same.


To know more about SEMP check out SEMP overview.

Option 3: Using SEMP and curl

Here is a list of curl commands that can accomplish the REST Delivery Point creation similar to Postman.

Update RC_HOST and RC_PORT to capture the HOST and PORT that your REST consumer application will be listening on along with VPN_NAME with the Message VPN name.

Also, replace the ADMIN_USER_NAME and ADMIN_USER_PASSWORD with Solace user with admin privileges and password.

Create a Queue object
curl \
  -X POST 'https://CLOUD_BROKER_HOST:943/SEMP/v2/config/msgVpns/VPN_NAME/queues' \
  -d '{
      "accessType": "exclusive",
      "egressEnabled": true,
      "ingressEnabled": true,
      "msgVpnName": "VPN_NAME",
      "owner": "all",
      "permission": "delete",
      "queueName": "Q/rdp1/input"
  }'\
  -H 'Content-Type: application/json' \
  -u ADMIN_USER_NAME:ADMIN_USER_PASSWORD
      
Create Queue Subscription object
curl \
    -X POST 'https://CLOUD_BROKER_HOST:943/SEMP/v2/config/msgVpns/VPN_NAME/queues/Q%2Frdp1%2Finput/subscriptions' \
    -d '{
        "msgVpnName": "VPN_NAME",
        "queueName": "Q/rdp1/input",
        "subscriptionTopic": "solace/samples/rest"
    }'\
    -H 'Content-Type: application/json' \
    --user ADMIN_USER_NAME:ADMIN_USER_PASSWORD
      
Note: Since the queue name parameter contains '/' character, you have to select the queue name string in the URL and encode the URI component.
Create a REST Delivery Point object
curl \
    -X POST 'https://CLOUD_BROKER_HOST:943/SEMP/v2/config/msgVpns/VPN_NAME/restDeliveryPoints' \
    -d '{
        "clientProfileName": "default",
        "enabled": true,
        "msgVpnName": "VPN_NAME",
        "restDeliveryPointName": "rdp1"
    }'\
    -H 'Content-Type: application/json' \
    --user ADMIN_USER_NAME:ADMIN_USER_PASSWORD
      
Create a Queue Binding object
curl \
    -X POST 'https://CLOUD_BROKER_HOST:943/SEMP/v2/config/msgVpns/VPN_NAME/restDeliveryPoints/rdp1/queueBindings' \
    -d '{
        "gatewayReplaceTargetAuthorityEnabled": false,
        "msgVpnName": "VPN_NAME",
        "postRequestTarget": "/rest/tutorials",
        "queueBindingName": "Q/rdp1/input",
        "restDeliveryPointName": "rdp1"
    }' \
    -H 'Content-Type: application/json' \
    --user ADMIN_USER_NAME:ADMIN_USER_PASSWORD
      
Create a REST Consumer object
curl \
    -X POST 'https://CLOUD_BROKER_HOST:943/SEMP/v2/config/msgVpns/VPN_NAME/restDeliveryPoints/rdp1/restConsumers' \
    -d '{
        "enabled": true,
        "msgVpnName": "VPN_NAME",
        "remoteHost": "RC_HOST",
        "remotePort": RC_PORT,
        "restConsumerName": "rc1",
        "restDeliveryPointName": "rdp1",
        "tlsEnabled": false
    }' \
    -H 'Content-Type: application/json' \
    --user ADMIN_USER_NAME:ADMIN_USER_PASSWORD
      
Note: The values of RC_HOST and RC_PORT need to be updated with the host and port where the REST HTTP server is running. This will be updated as the REST endpoint host and port in the REST Delivery Point configuration.

Option 4: Using Solace CLI

The Solace Command Line Interface (CLI) is a text-based, interactive shell for configuring and monitoring Solace event brokers (available for Solace PubSub+ Software and Appliance Brokers). It allows a user to perform event broker administration, configuration and provisioning, and network troubleshooting tasks. The CLI automatically starts after the event broker powers up.

Reference guides to the Solace CLI can be found in these locations: Appliance CLI Commands and Software Event Broker CLI Commands.

The following script captures necessary commands in sequence to configure the above mentioned resources.


Note: Ensure that the values of VPNNAME, RC_HOST and RC_PORT are updated with correct values in the following CLI script fragment (Message VPN name, host and port where the REST server is running).


home
enable
configure

message-spool message-vpn "VPN_NAME"
    ! pragma:interpreter:ignore-already-exists
    create queue "Q/rdp1/input" primary
        access-type "exclusive"
        permission all "delete"
        subscription topic "solace/samples/rest"
        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 Event Broker using CLI, with a user with administrative privileges and execute the above script fragments.

ssh admin@BROKER_HOST
Solace - Virtual Message Router (VMR)
Password:

BROKER_HOST is the host name where the Broker is running.

At this the REST delivery point is configured and should be operational and connected to your REST consumer application. You can verify this using PubSub+ Manager 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.

To know more about Solace CLI check out Solace CLI overview.

We have successfully configured a REST Delivery Point using Solace CLI. Follow the instructions in the next section to send a POST request on the designated POST URL and see that it is delivered to the designated queue, and in turn retrieved on the REST consumer we started here - A Simple REST Consumer.

Sending a message

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

Diagram: Sending a Message

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://BROKER_HOST:BROKER_REST_PORT/solace/samples/rest -H "content-type: text/plain"

You will need to update HOST and PORT to match your Solace PubSub+ Broker HOST and configured 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://BROKER_HOST:BROKER_REST_PORT/solace/samples/rest -H "content-type: text/plain" -u <REST_USER>:<REST_PASSWORD

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 successfully published a message to a topic using the REST API, and have received that message through an RDP via a webhook / POST to a backend REST web server on the consumer.