DEV Community: Magali Boulet

Understanding and Testing the PubSub+ Event Portal REST API

Magali Boulet — Tue, 27 Oct 2020 11:30:54 +0000

Whether it is CI/CD pipelines, event flow documentation systems, or using PubSub+ Event Portal as the unique event design and documentation tool for all your events in your enterprise, I’m sure you would appreciate an API to gather all the information. This is why PubSub+ Event Portal provides a REST API, which is compliant with the OpenAPI specification.

The goal of this tutorial is to explain how this API works. It will also guide you through the steps needed to REST-enable Section 4 of this codelab (done using PubSub+ Event Portal GUI).

Understanding PubSub+ Event Portal REST API

The PubSub+ Event Portal REST API provides the ability to interact with the PubSub+ Event Portal using RESTful patterns. For instance, it provides ways to browse artefacts, create, update, and delete events or applications. This is an easy way to integrate systems in a programmatic manner with the PubSub+ Event Portal Designer and Catalog.

The PubSub+ Event Portal REST API has an OpenAPI specification document available at https://openapi.solace.cloud.

Prerequisites to access the REST API

In order to perform REST API calls, you need an API token. Follow the steps to get that token:

Log in to your PubSub+ Cloud account
Click on your name and go to the Token Management menu in the console
Click Create Token
Give it a name and enable read & write permissions for PubSub+ Event Portal. You could choose to only enable read or write, depending on your needs, but in this tutorial we are going to use both read and write access.
Click Generate Token and in the popup dialogue box click Copy to store a copy of the token.

Testing the Event Portal REST API

In this section, you are going to REST-enable Section 4 of this codelab, which was done using the PubSub+ Event Portal GUI.

From https://console.solace.cloud, click the PubSub+ Event Portal Designer , either by clicking on the left menu or the right-hand side Event Portal Designer menu.

Enter the Acme Rideshare domain, which is created by default.

As described in the codelab, we are going to follow these steps:

Create an application
Create an event
Update the created application to publish this event

**Creating the RideDropoffProcessor Application**

According to the Event Portal OpenAPI specification, to create an application using the POST verb for the Applications resource, we first need a domain id.

So, let’s get the Acme Rideshare domain id. For this, choose the tool you are comfortable with to perform HTTP requests. This tutorial uses Postman, but curl would also be fine. To get the domain id, use the GET verb on the applicationDomains resource with the name parameter.

You should then use the following parameters:

Url: https://solace.cloud/api/v1/eventPortal/applicationDomains?name=Acme%20Rideshare
HTTP verb: GET
HTTP Authorization header: add the previously generated token as Bearer Token

If you are using Postman, you should get the following response:

In the response, locate the id element. This is your domain id. In this example, the id is pjn25g5eqlz.

You can now go ahead and create your application by using the following settings:

Url: https://solace.cloud/api/v1/eventPortal/applications
HTTP verb: POST
HTTP Content-type: application/json
HTTP Authorization header: add the previously generated token as Bearer Token
Payload: make sure you use your own domain id


{
"name": "RideDropoffProcessor",
"description": "Application created by Solace Event Portal REST API",
"applicationDomainId": "pjn25g5eqlz",
"revisionComment": "application creation",
"applicationClass": "unspecified"
}

If you are using Postman to post this request, you should get the following response:

At this stage, write down your application id (you will need it at a later step). In this example, the application id is q956yss2nqj.

Switch back to Designer, in the Applications tab, you now see the newly created application. In my case, it is at the end of the list:

Creating the Event RideAverageUpdate

Start by understanding the OpenAPI specification to create an event.

The mandatory elements are name and topic, but since we are following Section 4 of the codelab, we also need to link this event to a schema id. This means that the schema has to be created first, and then we’ll get its id.

So, let’s first create the schema. Same as before, we start by having a look at the OpenAPI specification for creating a schema.

In our context, this means:

Url: https://solace.cloud/api/v1/eventPortal/schemas
HTTP verb: POST
HTTP Content-type: application/json
HTTP Authorization header: add the previously generated token as Bearer Token
Payload: (make sure you use your own domain id)


{
"name": "RideAveragePayload",
"shared": false,
"description": "Event Payload which contains average meter readings, average passenger counts, and the number of rides in a given window duration",
"revisionComment": "Schema creation",
"contentType": "JSON",
"content": "{ \"$schema\": \"http://json-schema.org/draft-07/schema\",\"$id\": \"http://example.com/example.json\",\"type\": \"object\",\"title\": \"The root schema\",\"description\": \"The root schema comprises the entire JSON document.\",\"default\": {},\"examples\": [{\"timestamp\": \"2020-06-04T20:09:59.99832-04:00\",\"avg_meter_reading\": 21.615217,\"avg_passenger_count\": 1.5,\"window_duration_sec\": 300,\"window_ride_count\": 5}],\"required\": [\"timestamp\",\"avg_meter_reading\",\"avg_passenger_count\",\"window_duration_sec\",\"window_ride_count\"],\"additionalProperties\": true,\"properties\": {\"timestamp\": {\"$id\": \"#/properties/timestamp\",\"type\": \"string\",\"title\": \"The timestamp schema\",\"description\": \"An explanation about the purpose of this instance.\",\"default\": \"\",\"examples\": [\"2020-06-04T20:09:59.99832-04:00\"]},\"avg_meter_reading\": {\"$id\": \"#/properties/avg_meter_reading\",\"type\": \"number\",\"title\": \"The avg_meter_reading schema\",\"description\": \"An explanation about the purpose of this instance.\",\"default\": 0.0,\"examples\": [21.615217]},\"avg_passenger_count\": {\"$id\": \"#/properties/avg_passenger_count\",\"type\": \"number\",\"title\": \"The avg_passenger_count schema\",\"description\": \"An explanation about the purpose of this instance.\",\"default\": 0.0,\"examples\": [1.5]},\"window_duration_sec\": {\"$id\": \"#/properties/window_duration_sec\",\"type\": \"integer\",\"title\": \"The window_duration_sec schema\",\"description\": \"An explanation about the purpose of this instance.\",\"default\": 0,\"examples\": [300]},\"window_ride_count\": {\"$id\": \"#/properties/window_ride_count\",\"type\": \"integer\",\"title\": \"The window_ride_count schema\",\"description\": \"An explanation about the purpose of this instance.\",\"default\": 0,\"examples\": [5]}}}",
"applicationDomainId": "pjn25g5eqlz"
}

If you are using Postman to post this request, you should get the following response:

Copy and paste the id from the response. In my case, the schema id is q956yss2o5t. If you switch back to Designer and go to the Schemas tab, you’ll see the newly created schema.

You can now create the RideAverageUpdate event using the following settings:

Url: https://solace.cloud/api/v1/eventPortal/events
HTTP verb: POST
HTTP Content-type: application/json
HTTP Authorization header: add the previously generated token as Bearer Token
Payload: make sure you add your own schema id and domain id


{
"name": "RideAverageUpdate",
"shared": false,
"topicName": "taxi/nyc/v1/stats/dropoff/avg",
"description": "This event contains the average cost of rides over a specified duration",
"schemaId": "q956yss2o5t",
"applicationDomainId": "pjn25g5eqlz",
"revisionComment": "Event creation",
"brokerType": "solace",
"type": "event"
}

At this stage, write down your event id (you will need it at a later step). In this example, the event id is q956yss2oiv.

Finally, switch back to Designer to visualize the RideAverageUpdate event that was created.

You can also check the details of the event and you’ll find attached the RideAveragePayload schema:

Update the created application

Finally, in order to complete Step 4 of the codelab, you need to update the application RideDropoffProcessor to publish the RideAverageUpdate event. As always, start by understanding how to update an application by reading the OpenAPI specification, in the Applications resource, PATCH verb.

We need the application id (which will be added to the URI) and the fields that need to be updated. In this example, they are the revisioncomment element and the producedEventIds element.

You can now update the application with the following settings:

Url: https://solace.cloud/api/v1/eventPortal/applications/q956yss2nqj (make sure you use your own application id)
HTTP verb: PATCH
HTTP Content-type: application/json
HTTP Authorization header: add the previously generated token as Bearer Token
Payload: make sure you add your own event id


{
"revisionComment": "Changed published event",
"producedEventIds": [
"q956yss2oiv"
]
}

If you are using Postman, you should get a response similar to the one below:

Finally, switch back to Designer to see the event RideAverageUpdate published by the RideDropoffProcessor application:

You can also check the application revision history by clicking the three dots button at the end of the application line:

The revision history displays the update performed:

Optional last step: AsyncAPI generation

Now that you have created the application RideDropOffProcessor, you can now begin implementing it. But where to start? And how? One easy way is to start with AsyncAPI, and then use an AsyncAPI code generator.

AsyncAPI has emerged as the industry standard for defining asynchronous, event-driven APIs. You can think of it as OpenAPI for the asynchronous world. It is an open source initiative that provides both a specification to describe and document your asynchronous applications in a machine-readable format, and tooling (such as code generators) to make life easier for developers tasked with implementing them.

The Event Portal REST API enables you to automate the creation of an AsyncAPI document. That will define the application you want to develop. This step describes how to generate this document using the REST API.

So, let’s have a look at the AsyncAPI resource in the PubSub+ Event Portal REST API.

All you need is the application id, which you got previously. It will be passed in the URI and the AsyncAPI version to be generated which will be part of the payload to be sent. You can then generate your AsyncAPI document for the application by using the following settings:

Url: https://solace.cloud/api/v1/eventPortal/applications/q956yss2nqj/generateAsyncApiRequest (make sure you use your own application id)
HTTP verb: POST
HTTP Content-type: application/json
HTTP Authorization header: add the previously generated token as Bearer Token
Payload:


{
"asyncApiVersion": "2.0.0"
}

If you are using Postman, you should get a similar response:

The response contains the AsyncAPI document, describing the RideDropOffProcessor application. Looking for a next step to generate the application code? Refer to Steps 5 and 6 of the codelab.

Conclusion

PubSub+ Event Portal is an excellent tool to design and visualize your event-driven architecture, discover what events exist, and collaborate with your team. Using its REST API, you can automate the creation and modification of all your event-driven artefacts. Using AsyncAPI, your developers can generate the application code skeleton by leveraging the AsyncAPI code generator. If you have any questions about PubSub+ Event Portal and its REST API, post them to the Solace Developer Community.

The post Understanding and Testing the PubSub+ Event Portal REST API appeared first on Solace.

Integrating IoT Devices with Datacenter Resources on the SigFox Network

Magali Boulet — Wed, 17 May 2017 05:00:00 +0000

We’ve recently been doing some work with a French company called Sigfox that has some ambitious goals for enabling the Internet of Things. Rather than using a general-purpose IP-based cellular network, which requires significant power and silicon for basic connectivity, they’ve developed a purpose-built network designed to meet the needs of millions or even billions of low-powered IoT devices. They believe they can reduce power requirements enough that many devices can run without batteries (powered by solar for example) and with a fraction of the communications silicon required to connect via other wireless networks. Exciting stuff!

At Solace, we have taken a similar approach to tackling the challenges of data movement by tackling the right tools for the right jobs. Sophisticated messaging and streaming in the back office, WAN optimization for efficient cloud synchronization and lightweight protocols and APIs for IoT devices.

This shared vision is what brought our two companies together and what has led to some of my efforts building a proof-of-concept application that shows the capabilities of our combined solutions. Sigfox brings best-in-class connectivity for sensors and devices, and Solace brings a flexible means of delivering that data to enterprise apps.

In the PoC, Sigfox device data is distributed to two databases (SAP Hana and Cloudant), as well as to a mobile application using MQTT. I have deployed these two databases in two different public cloud: SAP Hana in AWS and Cloudant in Buemix, as shown below:

This PoC features Solace open data movement and SigFox IoT network capabilities:

Bridging low-powered devices with Enterprise applications
Messaging protocol transformation
Dynamic message and stream routing
Fan in from many devices
Fan out to many enterprise applications
Easy configuration
Decoupling consumers from producers
Scalable and resilient architecture
Choice of public clouds

I have worked with Sigfox to connect test devices to a Solace appliance deployed in our London offices. Messages sent by the devices are published to a topic that with subscribers in both SAP Hana and Cloudant.

Here’s the sensor data collection portal management site: https://www.sensit.io

Solace Configuration

Configuration in Solace for running this demo simply consists in:

Activating REST and MQTT service ports
Configuring HTTP(S) targets for sending messages to Hana and Cloudant. No coding is required.

Note: there is no need to configure anything for the MQTT mobile connectivity: by default, any message received by Solace is available to any supported protocol (if the security mechanisms permit). So, a MQTT client can easily subscribe to the messages posted by Sigfox.

It has been decided to include the sensor ID in the URI: Sigfox sends the sensor information to a URL like http://solace:port/

The configuration of the HTTP targets to send POST over HTTP (or HTTPS) messages is accomplished using the REST Delivery Point object which is bound to a REST Consumer and a Queue binding:

The REST Consumer object defines the target of the POST over HTTP(S) message
The Queue binding is used to attract messages (based on a topic namespace) to be sent by a REST Consumer.

The below schema summarizes the Solace configuration:

The same configuration has been done for Hana.

Let’s have a look at what happens when running the demo.

The sensor is configured to send light information every hour. This can be configured a more or less frequent update period – up to 8 messages per sliding hour, which is a limit by Sigfox network. Also, you can force the sensor to send information by pushing a button, which is handy for the demo.

At each update, the sensor data is sent by Sigfox to Solace, which then distributes to Hana, Cloudant and the Mobile MQTT client installed on my iPhone.

In Cloudant, there is a very easy and intuitive user interface showing all the database documents:

The DeviceID displays the identifier of the sensor and the rest of the columns represent information sent by Sigfox sensor.
Let’s have a look at the sensor information whose Sequence is #408:
Now let’s start browsing Hana using Studio for Hana and search for this same sequence number. The selected row on the below screenshot corresponds to the same sequence number #408 and contains the same sensor information.

Finally, let’s have a look at the Mobile MQTT app for iPhone:

First you need to fill in connectivity information to the Solace broker:
Then, using the Subscribe menu, you type the sensor id:
And finally the message with sequence number #408 is received:

Conclusion

Implementing Solace’s open data movement capabilities in conjunction with Sigfox’s innovative connectivity solution for sensors and devices has some serious potential. I look forward to seeing how our customers tap into the combination to link IoT devices with enterprise applications and business processes.

The post Integrating IoT Devices with Datacenter Resources on the SigFox Network appeared first on Solace.

Demonstrating IoT at SAP TechEd Barcelona

Magali Boulet — Tue, 15 Nov 2016 06:00:00 +0000

Last week I attended SAP TechEd in Barcelona. As a strategic partner of SAP, Solace had a booth where I had set up an Internet of Things demo. It consisted of a toy train carrying a sensor which collected information about temperature, direction and speed, and sent the data to a Raspberry Pi via Bluebooth. The Raspberry Pi in turn published this information to a topic in a Solace appliance in London using the MQTT protocol. A consumer represented by a Java program deployed locally on my Macbook in Barcelona subscribed to the topic and provisioned an influx database, which was used by a Grafana Dashboard to display the sensor information.

Here is the architecture of the demo:

This simple demo illustrated the ability of Solace to easily provide a pub/sub architecture that’s robust, scalable and highly available. On top of this, Solace serving as the messaging back-bone of SAP Hana Cloud Platform was another real life example of the reliability of our solution, being used already in many SAP datacenters worldwide.

Tweets of the demo:

Our #iot demo is ready! Come to the #solacedotcom booth #SAPTechEd pic.twitter.com/Vr12AC96It

— Magali Boulet (@magaliboulet ) November 8, 2016

Come visit our booth #SAPTechEd pic.twitter.com/JOvpcRVoQF

— Magali Boulet (@magaliboulet ) November 8, 2016

Here’s a video I made of the demo:

The post Demonstrating IoT at SAP TechEd Barcelona appeared first on Solace.