Versioning

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.