Managing Services with the PubSub+ Cloud REST API

A common practice when developing and deploying applications in a cloud environment is to bring up a cloud resource using the cloud provider’s APIs, use that resource, then remove it when testing is complete. Since this is all accomplished programmatically, there is no need to manually start or stop the resources with the cloud provider’s user interface.

For example, a common flow for testing an application would be to:

  1. Bring up a cloud server (for example, AWS EC2) programmatically.
  2. Install and test the app on that cloud server.
  3. Tear down the cloud server when your testing is complete.

Likewise, on PubSub+ Cloud, you can use the PubSub+ Cloud REST AP to create event broker services and extract information about them.

This tutorial shows you how to:

Before you Begin

You can start this tutorial, you'll require the following:

  • A PubSub+ Cloud account and event broker service.
  • Your account must be assigned the Administrator or Cluster Manager Editor role.
  • An API token must be available in the account with at least the following permissions:
    • Either the Get My Services or Get Services permission (both are recommended for this tutorial)
    • Create Services
    • Delete Services
    • Get Cluster Information
    • Update Cluster Name

    For more information, see Creating an API Token.

  • A way to send REST messages from your development environment. We use Postman in this tutorial. You can use the Solace Blogs – Create Messaging Service Postman collection and click the Run in Postman button to import the collection to Postman, which permits you to easily work through the steps in this tutorial.

    At this time, the documentation on the Solace Blogs about the PubSub+ Cloud REST API may be out of date. Refer to the documentation on this website for instructions about using the PubSub+ Cloud REST API.

    After you've set up the environment in Postman to use your API token, you can simply make each call by specifying the REST API. To check that API token is set up correctly to use Bearer authorization in Postman, select the Headers tab to validate that it is using Bearer Authorization and set it to use the apiToken environment variable that you had set up earlier. For example, you can see that Authorization is set up to use Bearer and the apiToken in the following illustration:

Creating an Event Broker Service using the REST API

You can use the PubSub+ Cloud REST API to create an event broker service. Some considerations when you create a service:

  • You fill must provide values for the following name-value pairs:
    • name— a unique name for the service
    • serviceTypeId— the type of service to create such as developer or enterprise
    • serviceClassId— with the class of the service, such as developer or enterprise-kilo

    For information on the values, see the PubSub Cloud API documentation.

    For trial accounts, only one developer account can be created.

  • Ensure that the API token you are using has been granted the permission Create Services.
  • Your account permits the service to be created. For example, for trial accounts, you are permitted to have one developer account so if you have a service created already, the API call will fail.

Follow these steps to create an event broker service.

  1. In the Solace Blogs – Create Messaging Service Postman Collection, select the POST Create Messaging Service request.
  2. For the POST command, fill the Body with the following information:
    • The name object is prefilled as Demo Service. You can use a different name here if you want.
    • The {{dataserviceId}} to name of the data center. For this example, we'll set it to aws-us-east-1b.
    • serviceTypeId and serviceClassIddeveloper
  3. Click Send. You should see a response that shows that service was created like the following illustration:

  4. A service takes a few minutes to create so wait a few minutes, and then go back to the PubSub+ Cloud Console and in Cluster Manager,you should see your service.

You have successfully created an event broker service. In the response is a serviceId, you may want to add this as variable or make it note of it for future commands. To add the {{service variable, click Environment quick look (eye icon) to specify the {{serviceId}} variable with the value of the serviceId from the response. You can also use optional parameters when you create your service to do the following:

Selecting the Event Broker Service Version using the REST API

You can choose the event broker service version to use when creating an event broker service using the REST API. To do this, use POST to https://api.solace.cloud/api/v0/services with the optional attribute of eventBrokerVersion to create the service. A successful response returns 201 (Created), otherwise one of the following responses are returned with a subcode (if applicable):

  • 400— a bad request occurred for the following reason:
    • 5000_102—an unsupported version was specified.
      • Suggested resolution: Issue a GET to https://api.solace.cloud/api/v0/eventBrokerVersionswith the parameters serviceClassId and dcId set where serviceClassId is the service class and dcId is datacenter id. For example, running https://api.solace.cloud/api/v0/eventBrokerVersions?serviceClassId=developer&dcId=aws-us-east-1b gives the following list of versions:
        {
        "data": [
           {
             "versionId": "9.6",
             "defaultVersion": true,
             "portRemappingEnabled": true,
             "redundancyGroupSslEnabled": false,
             "portDisablingEnabled": true
            }
        ]
        }
      • The returned information is:  
        • versionId: The version that can be used to create the service.
        • defaultVersion: Whether the specified version is the default version.
        • isPortDisablingEnabled: Whether the event broker version supports port disabling.
        • isPortRemappingEnabled: Whether the event broker version supports port remapping.
        • isRedundancyGroupSslEnabled: Whether theversion supports encrypted High-Availability (HA) links.

For example, the following JSON is for a REST API call to create a service with an event broker service version of 9.6:

POST /api/v0/services
{
  "name": "myfirstservice",
  "serviceTypeId": "enterprise",
  "serviceClassId": "enterprise-kilo",
  "adminState": "start",
  "datacenterId": "azure-eastus2",
  "eventBrokerVersion": "9.6"
}

Configuring the Message Spool Size using the REST API

You can configure the Message Pool size using the PubSub+ Cloud REST API. To do this, use a POST to https://api.solace.cloud/api/v0/services with the optional attribute of messageStorage to create the service. The range can be from 1 to 800, in GB. It's important to note that after you've set the limit, it cannot be changed. For information about creating a service using the REST API, see Creating an Event Broker Service using the REST API.

For example, the following JSON is for a REST API call to create a service with a Message Spool Size of 700 GB:

POST /api/v0/services
{
  "name": "myfirstservice",
  "serviceTypeId": "enterprise",
  "serviceClassId": "enterprise-kilo",
  "adminState": "start",
  "datacenterId": "google-eastus2",
  "eventBrokerVersion": "9.8"
  "messagingStorage": 700
}

A successful response returns 201.

Configuring the Cluster Name Using the REST API

To create a DMR cluster, each event broker service in the cluster must have the same cluster name. You can configure the cluster name for a service using the PubSub+ Cloud REST API to set up your DMR cluster. To do this, use a POST to https://api.solace.cloud/api/v0/services with the optional attribute of clusterName to create the service. A valid name is 1 to 64 characters long and can contain only alphanumeric characters, dashes, and underscores.

After you have set up your event broker services to have the same cluster name and you're ready to create the DMR cluster. To start this, contact contact Solace as the ability to create the DMR cluster is not yet available.

A successful response returns 201 (Created), otherwise one of the following responses are returned with a subcode (if applicable):

  • 400— with a support code of 102, which indicates that an invalid request was made. The reason it failed is for one or more of the following reasons:
    • the cluster name specified was not 1 to 64 characters in length
    • the cluster name specified has characters other than alphanumeric, dashes, or underscores
    • the version for eventBrokerVersion that was selected is not supported (event broker services that are supported must be 9.8 or later)

Creating an event broker service with a custom cluster name is supported for Kubernetes [for Virtual Private Cloud/Virtual Network (VPC/VNet) and on-premises deployments] that includes Google Cloud, customer private regions, and Solace-dedicated regions. This call currently can't be used in AWS or Azure public regions.

For example, the following JSON is for a REST API call to create a service with a cluster name of My-First-Cluster:

POST /api/v0/services
{
	"name": "service-1",
	"serviceTypeId": "developer",
	"serviceClassId": "developer",
	"adminState": "start",
	"redundancyGroupSslEnabled": true,
	"msgVpnName": "service-1",
	"cluster": {
		"name": "My-First-Cluster"
  	},
	"datacenterId": "gke-gcp-us-east1",
	"eventBrokerVersion": "9.8",
	"partitionId": "default",
	"attributes": {
		"customizedMessagingPorts": {
			"serviceAmqpPlainTextListenPort": 0,
			"serviceAmqpTlsListenPort": 5671,
			"serviceMqttPlainTextListenPort": 0,
			"serviceMqttTlsListenPort": 8883,
			"serviceMqttTlsWebSocketListenPort": 8443,
			"serviceMqttWebSocketListenPort": 0,
			"serviceRestIncomingPlainTextListenPort": 0,
			"serviceRestIncomingTlsListenPort": 9443,
			"serviceSmfPlainTextListenPort": 0,
			"serviceSmfCompressedListenPort": 0,
			"serviceSmfTlsListenPort": 55443,
			"serviceWebPlainTextListenPort": 0,
			"serviceWebTlsListenPort": 443
		}
	}
}

Changing the Cluster Name for an Existing Event Broker Service Using the REST API

You may have an existing event broker services that you want to add to an DMR cluster. To start this, you must change the current cluster name to match the cluster name for another service. You can change the cluster name using the PubSub+ Cloud REST API provided your API Token has at least the following permissions:

  • Get Cluster Information
  • Update Cluster Name

An event broker service cluster name can be changed if the following conditions are specified:

  • The event broker service whose cluster name is being changed is not part of an event mesh. If it is, that event broker service must first be removed from the event mesh.
  • Th new cluster name specified is 1 to 64 characters in length and contains only alphanumeric characters, dashes, or underscores.
  • The event broker service is a broker version of 9.8 or later.

The following is a suggested workflow to change the cluster name for an event broker service

  1. (Optional) Determine if the cluster name can be edited. For more information, see Determining if the Cluster Name for an Event Broker Service Can Be Edited.
  2. (Optional) Determine what existing cluster names are available for use in the account. For more information, see Getting the Cluster Names Available Using the REST API.
  3. Edit the cluster name using either a new name or an existing name. For more information, see Editing the Cluster name for an Existing Event Broker Service. You can also use the same call from the previous step to validate that your cluster name was created for the service.

Determining if the Cluster Name for an Event Broker Service Can Be Edited

The cluster name for an event broker service can be changed only if there are no pre-existing DMR external links are configured on the event broker service- in other words, it isn't part of an event mesh. The event broker service must also be an event broker version that is 9.8 or later.

To validate, issue a GET to https://api.solace.cloud/api/v0/admin/infrastructures/{infrastructureid}/clusterInfo. A response that is returned that indicates whether the cluster name can be edited in the supportsClusterRename property. A value of true indicates that it can be changed, while a value of false indicates it cannot. When it is false, it indicates that there are DMR external links configured on the service.

To determine the value for {infrastructureId}, issue a GET response to the event broker service using its service identifier and from the response get the infrastructureId. For example, a GET https://api.solace.cloud/api/v0/services/de472ut2xic and from the response, the infrastructureId is u9bs2tiij8e . For more information getting information about getting information about an event broker service, see Getting the Connection Details for the Event Broker Service using the REST API.

Note to make this call, you must set Solace Element Management Protocol (SEMP) over Message Bus to Enabled. This is enabled from the service details page in the PubSub+ Cloud Console on the Manage tab > Advanced Options for an event broker service.

For example, a GET response https://api.solace.cloud/api/v0/admin/infrastructures/u9bs2tiij8e/clusterInfo returns the following response to indicate that it is possible to edit the existing cluster name for the specified infrastructureId. A successul operations returns a response status of 200:

{
    "infrastructureId": "u9bs2tiij8e",
    "infrastructureName": "nano-daily-dev-u9bs2tiij8e",
    "infrastructure": {
        "supportsClusterRename": true
    },
    "errorMessage": null,
    "type": "infrastructureClusterInfo",
    "id": "u9bs2tiij8e"
}

Editing the Cluster name for an Existing Event Broker Service

You can edit the cluster name, provided the cluster name is considered editable. Though not necessary, it is possible to determine whether the cluster is editable prior to attempting to do it. For more information, see Determining if the Cluster Name for an Event Broker Service Can Be Edited.

You can specify a new name or using a pre-existing cluster name. You can get the list of pre-existing cluster name available in the account if you want. For more information about how to do this, see Getting the Cluster Names Available Using the REST API.

To edit the name of the cluster for an event broker service, POST to https://api.solace.cloud/api/v0/infrastructures/{infrastructureid}/requests/dmrClusterNameUpdateRequests and set dmrClusterName in the body of the request to cluster name you want. To determine the {infrastructureId}, issue a GET response to the event broker service. For more information getting information about a service, see Getting the Connection Details for the Event Broker Service using the REST API.

For example, for the infrastructureid of u9bs2tiij8e, issue the POST request https://api.solace.cloud/api/v0/infrastructures/u9bs2tiij8e/requests/dmrClusterNameUpdateRequests with the following payload in the body:

{
  "dmrClusterName" : "MyFirstCluster"
}

A successful response returns 202 (Created), otherwise a 400 response is returned to indicate that the cluster name was not changed.

Here's what a successful response looks like, where dmrClusterName specifies the new cluster name:

{
  "data": {
  "id": "c98m7382xht",
  "creationTimestamp": 1630688550818,
  "dmrClusterName": "MyFirstCluster",
  "type": "dmrClusterNameUpdateRequest"
  }
}

Getting the Cluster Names Available Using the REST API

You can get the cluster names available for an account. This might be useful so you can identify an existing cluster name to which to set your event broker service.

To determine the cluster names available, issue a GET to https://api.solace.cloud/api/v0/serviceClusterNames?detail=true (for detailed information about the cluster names and event broker services using that cluster name) or https://api.solace.cloud/api/v0/serviceClusterNames?detail=false (for a simple the list of the cluster names).

For example:

{
  "data": [
  {
    "clusterName": "MyFirstCluster",
    "serviceNames": [
                     "My-Second-Service",
                     "My-First-Service"
                    ],
    "type": "clusterNames"
  },
  {
    "clusterName": "cluster-gke-gcp-us-central1-a-p9fqu5ymy3i",
    "serviceNames": [
                     "My-Third-Service"
			        ],
			"type": "clusterNames"
  }
  ],
  "meta": {
           "currentTime": 1630689531325,
           "pageNumber": 0,
           "pages": {
              "next-page": null,
              "total-pages": 1
           },
           "count": 3,
           "pageSize": 100
          }
   }
  }
}

Configuring Hostnames Using the REST API

You can configure hostnames for an existing event broker service using the PubSub+ Cloud REST API and the service identifier of the event broker service. The service identifier is part of the response returned when you create an event broker service or retrieved via a GET. retrieved. For information about creating an event broker service or retrieving the service identifier using the REST API, see Creating an Event Broker Service using the REST API and Getting the Connection Details for the Event Broker Service using the REST API, respectively.

Operations to configure a hostname occur asynchronously. For this reason, you may see a delay before the operation completes. Using the REST API, you can perform the following operations to configure hostnames on an event broker service:

To add, move, or delete a hostname for event broker services you own or in your organization, you require an API token with the Update Service permission under My Services and Organization Services, respectively. For more information about API tokens, see Managing API Tokens.

For information about managing event broker services using the REST API, see Managing Services with the PubSub+ Cloud REST API.

Adding a Hostname Using the REST API

You can add a hostname using the REST API to an existing event broker service.

To perform this operation, you must know the service identifier for your event broker service.

To add a hostname to an existing event broker service, use a POST call to https://api.solace.cloud/api/v0/services/{service_id}/serviceHostNames with the data parameters serviceHostName as the hostname and operation as create. A successful response returns 202 (Accepted), otherwise one of the following responses are returned with a subcode (if applicable):

  • 400 — a bad request occurred for one of the following reasons:
    • 5000_5800 — the specified hostname is already being used for an event broker service
      • Suggested resolution — specify a different hostname
    • 5000_5802 — the event broker service already has five additional hostnames configured

      • Suggested resolution — the maximum number of hostnames has already been configured; you can remove an existing hostname and try again

    • 5000_5803 — the hostname that was specified cannot be longer than 255 characters

      • Suggested resolution — the maximum number of hostnames has already been configured; you can remove an existing hostname and try again

  • 404 — the specified event broker service does not exist
    • Suggested resolution — check that the event broker service has been created and that the service_id is correct

For example, the following JSON shows a REST API call to create the hostname, mytesthostname:

POST /api/v0/services/24iadhkgu1/serviceHostNames
{  "serviceHostName": "mytesthostname", 
   "operation": "create"
}

Here's an example of a successful 202 response:

{
  "id": "24iadhksu1",   
"job": null,
"serviceId": "24iadhkfzh",
"requestType": "serviceHostNameRequest",
"creationTimestamp": 1608069258621,
"requestAttributes":
{ "serviceHostName": "mytesthostname",
"operation": "create" } }

To access the event broker service, you can use mytesthostname.messaging.solace.com as a hostname.

Deleting a Hostname from an Event Broker Service Using the REST API

You can remove a hostname from an event broker service. To perform this operation, you must know the service identifier for your event broker service. It's important to understand that you cannot remove the default name that's assigned to the event broker service. For information about retrieving the service identifier using the REST API, see Getting the Connection Details for the Event Broker Service using the REST API.

To remove a hostname from an event broker service, use a DELETE call to https://api.solace.cloud/api/v0/services/{service_id}/serviceHostNames with the data parameters serviceHostName as the hostname to delete and operation as delete.. A successful response returns 202 (Accepted), otherwise the following response is returned:

  • 404—the specified event broker service or specified hostname for the event broker service doesn't exist
    • Suggested resolution—check that event broker service exists or the hostname exists on the specified event broker service.

For example, the following JSON is for a REST API call to delete the hostname of mytesthostname:

DELETE/api/v0/services/24iadhkgu1/serviceHostNames
{  "serviceHostName": "mytesthostname",  
   "operation": "delete"
}

Here's an example of a successful 202 response:

{
  "id": "24iadhkgu1",   
"job": null,
"serviceId": "24iadhkfzh",
"requestType": "serviceHostNameRequest",
"creationTimestamp": 1608069258621,
"requestAttributes":
{ "serviceHostName": "mytesthostname",
"operation": "delete" } }.

Getting the Connection Details for the Event Broker Service using the REST API

After you have created an event broker service, you can use the PubSub+ Cloud REST API to retrieve the service's connection details.

  1. In the Solace PubSub+ Cloud – Create Messaging Services Postman Collection, select the Get Messaging Service request.
  2. In the GET request URL, replace the {{serviceId}} variable with the identifier of the service you want to see. If you don't provide the specific {{serviceId}}, you can get all the services that you are permitted to see (i.e., issue a GET to https://api.solace.cloud/api/v0/services).
  3. Click Send.

    You should see the connection details in the response.

Deleting an Event Broker Service

You can use the PubSub+ Cloud REST API to delete an event broker service. Follow these steps to delete an event broker service.

  1. In the Solace Blogs – Create Messaging Service Postman Collection, select the DEL Delete Messaging Service request .
  2. In the DELETE request URL, replace the {{serviceId}} variable with the identifier of the service you want to delete.
  3. Click Send.

You should see a 200 OK response that indicates that the request was successful. Go back to the PubSub+ Cloud Console and in Cluster Manager,you should no longer see the service you delete or if you run a Get Service REST call, you will get a "Could not find service <serviceID> in your organization <organizationID>" message.