Solace Element Management Protocol version 2 (SEMP v2) is a RESTful API that provides a programmable way to configure PubSub+ event brokers. It complements the Solace CLI and Broker Manager.
The SEMP API makes it easy for you to provision, operate, and maintain your event brokers, whether in the public cloud, your private cloud, or your data center. SEMP can be easily integrated with configuration management portals or configuration automation tools like Chef, Puppet, Ansible, and others.
Solace has used the OpenAPI Specification (specifically OpenAPI Specification v2.0) to define the SEMP API. This specification (formerly known as Swagger) provides a standard, language-neutral way of defining REST APIs, which gives developers a fully documented SEMP API specification so they can get up and running quickly. The API specification describes the various SEMP objects, how they are represented, and what URIs and HTTP method each object supports.
The following SEMP v2 APIs are available:
Reading and writing configuration state.
Querying administrative and operational state.
Your SEMP application might use more than one of these three APIs. However, common application use cases will generally map to a single API.
The Configuration API allows you to read and write administrative state on the event broker. For example, you can use the Configuration API to:
create a queue
enable a queue
check whether a queue is administratively-enabled
The Monitoring API lets you read objects, including their configuration and the operational state of their attributes. Examples of this are:
checking if a client has bound to a queue
checking a queue’s stats
checking if the event broker is currently active for the message backbone
You can use the Action API to manipulate non-configuration state on the event broker. For example, you can:
delete messages from a queue
clear queue statistics
revert activity to an event broker's high-availability (HA) mate
SEMP v2 uses URIs to address manageable resources of the PubSub+ event broker. Resources are individual objects, collections of objects, or (exclusively in the Action API) actions. For more information, see SEMP Resources.
Following a conventional REST approach, SEMP v2 URIs can be decomposed as follows:
Protocol—The API supports both
Host and Port—Identify the event broker.
Base Path—Refers to the base path for the configuration, action, or monitoring API.
Query—Used to control behaviors like filtering and paging in various methods. For more information, see Query Parameters.
For example, if you were using cURL and wanted to get details about the SEMP v2 configuration API from a software event broker called
solace-broker, you would send a command like the following:
curl -X GET -u user:password solace-broker:8080/SEMP/v2/config/about
To obtain the SEMP API specification in a JSON format from an event broker, you can perform a GET on the following URI:
<api> is one of
You can also:
The SEMP API's use of the OpenAPI specification allows developers to easily generate client libraries in their favorite programming language. The Swagger tooling can export client libraries in over 25 different programming languages including:
See Getting Started with SEMP, below, for a link to the tutorials, including an example that shows how to generate a client library from a SEMP API specification.
Changes to the SEMP specification may affect the backwards compatibility of generated APIs. For details, see the SEMP API Reference.
The SEMP v2 API is being released iteratively. With each release, more commands and functionality are added. Refer to the specification files to see what is currently supported. To obtain the specification, see SEMP API Reference.
For commands and operations not yet supported in SEMP v2, use the legacy SEMP API.
The SEMP v2 and legacy SEMP request and response formats are entirely incompatible, although both protocols share a common port configuration on the event broker. They are differentiated by the initial portion of the URI path, either
To learn more about SEMP, see the following:
- SEMP API Versions—Provides an overview of the latest versions of the SEMP API, its supported and unsupported features, and the approach taken to ensure version compatibility as new features are introduced.
- SEMP API Architecture—Describes the design of the SEMP API, including its object model, query parameters, and HTTP methods and return codes.
- SEMP Authentication and Authorization—Provides instructions for authenticating a SEMP client.
- SEMP Features—Discusses frequently used SEMP features, such as filtering and paging, in detail.
- SEMP Error Handling—Lists common error codes and how to handle them.
- SEMP API Reference—Links to the API references for appliance and software broker versions of the API.
- Legacy SEMP—Describes how use the legacy SEMP API that existed prior to SEMP v2.
Click the button below to try the SEMP tutorials. There are two ways you can get started:
- If your company has PubSub+ event brokers deployed, contact your middleware team to obtain the hostname or IP address of an event broker to test against, a username and password to access it, and a Message VPN in which you can produce and consume messages.
- If you don't have access to an event broker, see Setting Up Container Images or Setting Up Machine Images for instructions for downloading and installing a software event broker, or start up an event broker service using PubSub+ Cloud.