Versioning
Lightspark strives to maintain stable APIs. We are aware that breaking changes in our APIs will result in more work for
our customers to upgrade their integrations. However, Lightspark also seeks to continuously evolve its services and old
APIs can hinder our ability to bring improvements and new features to our customers.
GraphQL is very flexible and most changes can be made on top of the existing API
and won’t require any upgrade on our customers' part. For the breaking changes,
we provide below a predictable SLA and path feature upgrades and deprecation.
A breaking change is any change to the API that requires clients to upgrade their integration in order to keep working.
Non-breaking changes are modifications to the API that do not break current clients. Here are some examples:
| Non-breaking changes | Breaking changes |
|---|---|
| Adding a field to a type. | Making a required field optional. |
| Adding a value to an enum. | Changing the type of a field. |
| Making an optional field required. | Renaming (remove + add) a type. |
| Adding an optional argument. | Removing a field. |
| Adding a new type to the schema. | |
| Adding a new top-level query/mutation. | |
| Marking a field/type as deprecated. |
The Lightspark SDKs follow the Semver 2.0.0 specification. This means that its version follows the format:
MAJOR.MINOR.PATCH (e.g. 1.2.3)- MAJOR is increased every time a non-backward compatible (breaking) change is introduced.
- MINOR is increased every time a backward compatible (non-breaking) change is introduced.
- PATCH is increased every time a backward compatible (non-breaking) bug fix is introduced.
The Lightspark SDK will likely follow closely the release of new API features. Just like for the API,
we will strive to make our SDK as stable as possible and only introduce breaking changes when necessary.
However, Lightspark may release more frequent SDK versions than API versions. This is because the API
does not need to be upgraded when adding non-breaking changes, while the SDK does.
Customers are not required to upgrade their SDK version if the features they use are already supported,
but it is recommended to upgrade whenever a new MAJOR version is released.
Since each SDK is pinned to a specific API version, the SDKs will follow the same deprecation lifecycle
as the API they are used with.
A new version will be released every time a breaking change is implemented in the Lightspark API.
Versions of the API follow the following format, represented by the day of their release:
YYYY.MM.DD (e.g. 2023-09-13)To select a version, you need to call the right URLs. They follow the following format:
https://api.lightspark.com/graphql/server/<API_VERSION> (e.g. https://api.lightspark.com/graphql/server/2023-09-13)Lightspark currently intends to maintain an API at least 3 months after its deprecation has been announced.
This means that once a new API has been released and we have informed our customers that their current
version will be deprecated, we will seek to give customers at least 3 months to migrate to the new version.
We may provide for longer transition periods in the future.
We will seek to help you migrate seamlessly, including by assisting with the identification of the deprecated
code paths in use in your developer center, and providing migration guides, plenty of reminders, and support
in case you need help upgrading.
Once an API version is deprecated, we will automatically redirect the calls to the oldest supported API.
Some of the calls might still work, while others may not.