Versioning is an important aspect of our REST APIs. Our APIs have different release versions available. We recommend that for production environments, you use APIs that are Generally Available.
Different versions of the REST API are available. Stable REST APIs have strict requirements around backward compatibility. In addition to specific versions, the REST APIs have different release stages with different commitments allowing rapid development while still upholding a predictable contract.
The version of the API takes the following format.
Major Version.Minor Version
Types of Releases for REST APIs
The REST APIs have similar releases to the types of releases specified in the Release Stages Overview. The following are descriptions that are specific to the REST APIs:
Early Access
For an Early Release, the APIs are:
- under active development and marked (Early Access)
- may not be documented
- breaking changes should be expected
- not guaranteed to become Generally Available
Beta
For Beta releases, the APIs are:
- fully featured with fewer changes
- documented and marked as (Beta)
- publicly available
- breaking changes may occur, but are less likely
General Availability (GA)
For GA releases, the APIs are:
- complete, stable, and fully supported
- fully documented
- if neither (Early Access) nor (Beta) is indicated in the documentation, the API is General Availability
- publicly available
- backward-compatible (except for critical security fixes)
- any breaking changes follow a deprecation strategy
Deprecation Rules for REST APIs
Deprecation of a Generally Available REST API signifies to you that Solace has a plan to remove it in a future release. The deprecation rules do not apply to Beta or Early Access APIs. For example, APIs can be changed or removed without notice.
Deprecated APIs in general are replaced with another REST API. The deprecation is indicated in the description of the part of the API being deprecated and can apply to:
- An entire REST API endpoint
- A query parameter
- A request or response property
All deprecated API endpoints, parameters, or objects indicate the deprecation in the description. When any part of an API is deprecated (request or response, query parameter, or entire API), the X-Solace-API-Deprecated header is included in the response of the API with a link to the documentation that indicates deprecation.
In addition, the following information is provided in the documentation:
- Deprecation Date—the date of deprecation in ISO8601 format
- Removal Date—the date of removal in ISO8601 format and the date is subject to change based on customer and business requirements.
- Reason— the reason it was deprecated and an alternative endpoint, parameter, or object where applicable.
Note
Emergency changes in PubSub+ Cloud for critical or security fixes may not follow standard deprecation rules.
Emergency Changes for REST APIs in PubSub+ Cloud
Emergency changes may not be compatible changes, but they are required due to security vulnerabilities or a violation of the specification.