SEMP

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:

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 http and https protocols.

• Host and Port—Identify the event broker.

  For information about which port to use, see Default Port Numbers (for appliances and software event brokers) and Client Application Connectivity and Security (for PubSub+ Cloud).

• 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—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.

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 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.