How to Use the Solace Cloud REST API to Manage Services¶
If you’re familiar with developing and deploying in a cloud environment, a common practice is to bring up a cloud resource using a cloud provider’s APIs, use that resource, then remove it when you are done. This is all accomplished programmatically, avoiding the need to start or stop the resources manually using the cloud provider’s user interface.
For example, a common flow for testing an app would be to:
- Bring up a cloud server (e.g., an AWS EC2) programmatically
- Install and test your app on that cloud server
- Tear down the cloud server when your testing is complete
Solace PubSub+ Cloud has introduced REST APIs and REST API token support (in beta). This means developers can use Solace Cloud’s REST APIs to create PubSub+ Cloud messaging services and extract information about them programmatically.
In this blog post, I’ll show you how you can:
- Grab an API token from Solace Cloud using your account
- Use that API token to create a messaging service via Solace Cloud’s REST APIs
- Use the REST APIs to pull out the MQTT connection details for the new messaging service (which could be used in your apps to send/receive MQTT messages)
- You know what REST is and kind of know how to send REST requests using your favorite tool.
But if you don’t, check out this REST intro and then come back.
- Sign up for Solace Cloud if you haven’t already – don’t worry, it’s free.
- You need a way to send REST messages from your dev environment. Postman (6.1.3 or greater) is a good choice if you want a visual REST API Dev Tool
- Click this link to import the Postman collection then hit the “Run in Postman” button.
If you don’t have Postman installed when you hit “Run in Postman”, it will prompt you to install it (which doesn’t take long). Once Postman is installed, you will need to shut it down and click on the “Run in Postman” link again to import the Postman collection. If you prefer using CURL, the Postman link above provides the sample CURL commands.
Create an API Token¶
You need an API token to authenticate and authorize REST requests. When creating an API token, you will configure what permissions it has (i.e., a subset of the permissions you have when you log in to Solace Cloud)
- Log in to Solace Cloud
- Click on your name in the right side of the menu bar to navigate to Token Management.
- Click the “Create Token” button
- Give the Token a name and enable these permissions:
- Get My Services
- Create Services
- Delete My Services
- Click the “Generate Token” button
- Copy the token to your clipboard by clicking the “Copy” button. Note: You will not see this again for security reasons. If you lose the token, you can always regenerate the token or create a new one.
- Set up Postman Collection Authorization – In order for Postman to send REST to Solace Cloud, you need to set the token you just created
- Set the Postman Environment to Solace PubSub+ Cloud – look in the drop down in the upper left part of the Postman window.
- Edit the Solace PubSub+ Cloud environment and set the token by clicking on eye icon next to the environment drop down. Then click Edit next to Solace PubSub+ Environment.
- Paste the token in the value field of the apiToken key. You must also select a service type and service class. For a free service, set the serviceTypeId to free and the serviceClassId to free as well. Once all the values are entered, click Update.
Great! Now we have a token, and Postman is set up to use it!
Let’s use it to do some stuff.
Create a Messaging Service using the REST API¶
Now that we have a token, we can use it call the service REST endpoint to create a messaging service.
- In the Postman Collection “Solace Blogs – Create Messaging Service”, select the request “POST Create Messaging Service”
- Click on the Send button,
You should see a JSON response confirming that a messaging service was created.
Now go back to Solace Cloud and you should see your service.
Awesome! You have just created a messaging service.
Get the Connection Details for the Messaging Service¶
Now let’s retrieve the messaging service connection details. The Solace PubSub+ Cloud Messaging Service supports almost all of the messaging protocols under the sun! Let’s pick MQTT for the sake of this exercise, but this API provides you with all supported protocols.
- In the Postman Collection “Solace PubSub+ Cloud – Create Messaging Services”, select the request Get Messaging Service.
- Click on the Send button
You should be able to see the MQTT connection details in the JSON response.
Now you can use the connection details to start sending MQTT messages to your new messaging service from your app.
You now have everything you need to create Solace PubSub+ Cloud messaging services in a cloud stylie way.
These REST APIs are still BETA, so any feedback is welcome. Please use the feedback section of the Support tab in the Solace Cloud console to let us know what you think.