Ably’s general approach to versioning is to use the semantic versioning scheme, with a few differences that are explained in this article. The approach outlined here applies to our client library SDKs, our REST API endpoints, and all other public endpoints that support versioning such as Server-Sent Events.
Our policy is that a
major.minor version number applies to the API specification and across all versioned services and protocols. Each library implementing a given version of the API specification adopts the same major and minor versions and has patch version numbering indicating the actual library revision.
Whilst we recognise this approach has some limitations – primarily around the need to synchronize version updates across multiple libraries and specifications when a breaking change is introduced into any one of them – we believe that having an independent series of version numbers for different protocols, endpoints and SDKs would make managing that very difficult for Ably and, most importantly, would be confusing for our customers. This documentation itself operates on the basis that customer-facing content shares a single version number so that customers can view the latest or, for example, switch to 1.1 across the entire site (for content that has been versioned).
Further, given that the version numbers we use cover the raw HTTP API, the protocol and API spec, and the client library SDKs, features such as support for connection/request params, channel params, extras, token lengths, APIs (eg push HTTP API) vary by the API version. Stateless connections are subject to some of those constraints, even if they don’t follow the full protocol spec or the library API.
As such, in the case of SSE for example, we believe that standardising on versioning means it is quite natural for a connection string for a stateless connection to include the spec version, and that will allow the system to know what features the client can be expected to understand, and might be required so that the system knows how to interpret param values that are supplied by the client. Whilst we always try to make it so that there are no incompatibilities, we have a version because we recognise that that is not always avoidable.
Please note that the realtime protocol used by our SDKs is an internal protocol, and thus breaking changes do not necessitate a major version change. A major version bump is preferred for breaking changes to public APIs.