SEMP API Versions
This section 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.
The current version of the SEMP API is v2. This SEMP version does not yet support all event broker commands—currently, this version supports most Message VPN-scoped configuration commands. For commands that are not yet supported in SEMP v2, you can continue to use the Legacy SEMP API.
When SEMP v2 and Legacy SEMP/CLI are used to request concurrent changes to the same object, the Legacy SEMP/CLI change might be applied between the individual changes associated with the SEMP v2 request. The end state of the object might then be a mix of both the Legacy SEMP/CLI and SEMP v2 requested changes, or the SEMP v2 request might fail and return an error. If possible, we recommend that you avoid using both Legacy SEMP/CLI and SEMP v2 to make concurrent changes to the same object.
For information on how and when changes to the SEMP API version may occur, refer to Future Releases and Compatibility.
The SEMP v2 API is being released iteratively with an initial focus on enabling Message VPN configuration on Solace PubSub+ event brokers. With each release, more commands and functionality are added. Refer to the spec files to see what is currently supported. Instructions for spec file access are presented on the page SEMP API Reference.
For commands and operations not yet supported in SEMP v2, use the legacy SEMP API.
In order to ensure that the SEMP API provides a stable API for clients, the following policies will be followed when introducing new features and functionality. New features and functionality will be delivered as part of new event broker loads.
- Within a given version of SEMP, Solace will only make Compatible Changes or Emergency Changes.
- If a new feature of functionality requires Incompatible Changes, a new version of the SEMP API will be released.
- For old versions of the SEMP API, Solace will follow the Legacy SEMP Support plan.
This means that client libraries generated with an older SEMP specifications will continue to work with newer event broker loads. However, a client library generated from a new schema may contain changes to interfaces to support new features. So it is not true that client libraries generated with newer SEMP specifications will maintain the same compile time method signatures.
The following changes are considered backwards-compatible and do not require a SEMP version change to introduce:
- Adding a new resource.
- Add a new attribute to a resource.
- Relocating or renaming an existing resource. The old URI will be marked as deprecated but will remain valid until the next version of SEMP.
- Relocating or renaming an existing attribute. The old attribute name will be marked as deprecated but both the old and new attribute will be valid until the next version of SEMP.
- Changing a return error code. Error code values and their meanings will never be changed. However, over time Solace may introduce new error codes that will be returned for a given method/URI combination. On a best-effort basis, for the same conditions, Solace will strive to return the same error code. When conditions change (for example, due to new features being added) newer error codes may be returned. Therefore client applications should be written to act sensibly when they receive error codes they do not understand.
The following changes are not backwards-compatible. To make these changes, a new version of SEMP will be released.
- Removing an existing URI.
- Removing an existing attribute.
- Removing an existing query parameter.
- Changing a default attribute value. SEMP exposes users to the default value of an attribute through POST and PUT. Given such, a change to a default value is not a backwards-compatible change, in that a user, if relying on the old default, will experience different behavior.
- Adding a restricting attribute property (that is, making an existing attribute one of “required”, “read-only”, “write-only”, or “requires-disable”) is in general a non-backwards compatible change.
Emergency changes may not be compatible changes, but they are required due to security vulnerabilities or a violation of the specification.