Clever is committed to providing the best experience for developers building on our platform. In order to make it easier and faster to build on Clever, we constantly improve by adding new features and deprecating ones that are redundant. Here’s what to expect from Clever when we make changes to our API.
Switching to a new API version
As of Back to School 2021, you will need to set the major version (e.g. v1, v2) that you will be using in production. If you are moving between major versions in production, please reach out to our Partner Engineering team to ensure a smooth transition.
Within a major version, you can freely make calls against any associated minor version (for example, you could use both 2.0 and 2.1, but not 3.0) by updating your URLS (e.g. https://api.clever.com/v2.1/district).
For detailed information on changing API versions, check out our developer documentation on Upgrading to the latest version of Clever’s API.
Major vs minor versions
We define a minor release as one that will only add new features (e.g. response fields, input parameters, endpoints, etc) and fix small bugs. Minor versions will be backwards compatible.
Major version releases may contain features that are not backwards compatible as well as feature deprecations.
Releasing a new API version
Clever is committed to releasing planned API versions no more than once a year, based on the following release timeline:
- New API versions will be announced by November.
- Rostering (data and events) API versions should be released by December.
- Identity API changes should be released by March.
Any delay in this timeline will be communicated to customers in advance. In case of an emergency, Clever reserves the right to release an API version outside of this schedule to meet customer needs with proactive communications to partners.
When a new version is fully released, new applications will build to the newest API version, and will not be able to use any previous version of the API.
Updating versions after release
While we consider new versions code complete upon official release, we recognize that bugs can slip by our testing processes! For three months after a version is released, we will make updates to the version to fix any discovered bugs. Once three months have passed, we will freeze the version as-is and make no further updates.
We sometimes need to make changes to all API versions - if we do, we will communicate this with partners as soon as possible.
Deprecating an existing API version
Clever will support no more than two major API versions at a time. This policy aligns with industry best practice to ensure a great front-end experience for you and your customers. This means that when a new major version is released, we will begin the deprecation and end of life process for the oldest major version.
We are committed to ensuring that deprecation goes smoothly for all customers. Therefore, the deprecation and end of life process is as follows:
- At least one year in advance of deprecation, Clever will send notice of deprecation to all partners. We will also reach out to partners who are using the API version to help determine their upgrade path and timeline.
- Once an API version is deprecated, Clever will provide only limited support for bug fixes.
- An API version will no longer be supported six months after it is deprecated. At this point, applications will be unable to access any of the version’s endpoints.
Upon announcement of API v3, we are officially beginning the deprecation and end of life process for API v1, which includes both v1.1 and v1.2. The version will be deprecated by Back to School June 2022 and no longer accessible by December 2022.