Versioning is an important aspect of our REST APIs, and we offer different versions of the REST APIs as we develop them. We recommend you use the Generally Available REST API for production environments.
Types of Releases for REST APIs
The REST APIs follow similar release stages as other PubSub+ Products. You can view a description of each release stage in the customer documentation at PubSub+ Cloud Release Stages Overview. The REST APIs have three versions:
- General Availablity (GA)
- Beta
- Early Access
GA REST APIs have strict requirements concerning backward compatibility compared with other API versions. When developing for production environments, we recommend using GA APIs.
You can find the details of each REST API release stage below.
General Availability (GA)
For GA releases, the APIs are:
- complete, stable, and fully supported
- fully documented
- if (Early Access) or (Beta) are not visible in the documentation, the API is GA
- publicly available
- any breaking changes follow a deprecation strategy
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
Early Access (EA)
For EA releases, 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
Deprecation Rules for REST APIs
Deprecation of a Generally Available REST API signifies that Solace plans to remove it in a future release. The deprecation rules do not apply to Beta or Early Access APIs. For example, Beta and Early Access 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 REST API may be required to address security vulnerabilities or specification violations. These changes may break compatibility, and may not follow standard deprecation rules.