SEMP
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.
The SEMP API was defined using the OpenAPI Specification (specifically OpenAPI Specification v2.0). 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:
| API | Base Path | Purpose |
|---|---|---|
|
Configuration |
/SEMP/v2/config
|
Reading and writing configuration state. |
|
Monitoring |
/SEMP/v2/monitor
|
Querying administrative and operational state. |
|
Action |
/SEMP/v2/action
|
Performing actions. |
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
URI Structure
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>://<host>:<port>/<base-path>/<resource-path>[?<query-parameter>]
-
Protocol—The API supports both
httpandhttpsprotocols. -
Host and Port—Identify the event broker.
For information about which port to use, see
-
Base Path—Refers to the base path for the configuration, action, or monitoring API.
-
Resource Path—The full path to the object or collection targeted by the request, as listed in the SEMP API Reference. For further details, see SEMP Resources.
-
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
Getting the Specification
To obtain the SEMP API specification in a JSON format from an event broker, you can perform a GET on the following URI:
/SEMP/v2/<api>/spec
where <api> is one of config, action, or monitor.
You can also:
- download the SEMP API specifications from the solace.com/downloads page
- view the SEMP API Reference
Generating Client Libraries
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:
- Android, C#, Java, Javascript, Node, Python, Ruby, Scala, and Swift.
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.
SEMP v2 Limitations
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 /SEMP or /SEMP/v2/.
Getting Started with SEMP
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
- Legacy SEMP—Describes how use the legacy SEMP API that existed prior to SEMP v2.
SEMP Tutorials
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 for instructions for downloading and installing a software event broker, or start up an event broker service using PubSub+ Cloud.