API Versions and YouPosted: 2014/07/11
As D2L moves towards continuous release for its Integrated Learning Platform, the lifecycle for legacy versions of the platform becomes more explicit, and this has a concrete effect on the versions you will be able to use of the Valence Learning Framework API. This blog post provides a simple explanation for what versions of the API will be supported, to what extent, and when that support will end. You can use this information to plan your transition from one version of the Learning Framework API to another.
How the API lifecycle works
To help you understand how the API lifecycle works, it will be good to remember that the API contract provided by the release of a product component is a feature of that release. That is, when we released LE 9.4.1, the LE v1.0 APIs were a feature directly tied to that platform. The support and lifespan of that API feature, then, is directly tied to the support and lifespan of the product component that introduced it.
End of maintenance and deprecation
When the version of a product component enters a time when it gets reduced support, when it reaches “end of maintenance”, it is no longer being actively maintained by D2L. Software defects or other product related issues are not investigated or resolved. No more service packs will be released for that version of the product component.
This also applies to the API contract feature introduced with that product component. When the API contract feature reaches end of maintenance, it becomes deprecated:
- The APIs in that contract version won’t receive prioritized support or attention by D2L: we may perform maintenance on the API routes, especially in response to critical or security-related issues, but these will get evaluated on a case-by-case basis, and we make no commitment to do the maintenance.
- You should now put a priority on planning the transition of all your work off the deprecated API contract.
End of support and obsolescence
When the version of a product component enters a time when it gets no support at all, when it reaches “end of support”, D2L will no longer provide support services for the product compoment.
This also applies to the API contract feature introduced with that product component. When the API contract feature reaches end of support, it becomes obsolete:
- The APIs in that contract version are eligible to have their access entirely removed from the back-end service of all in-market versions of the product component.
That point has an important implication: because the LE v1.0 API introduced on LE 9.4.1 and provided on that platform must remain the same as the LE v1.0 API also supported on LE 10.3.0, when D2L can’t make changes to the LE v1.0 API on LE v9.4.1, the consequence of that is that D2L can’t make changes to that API version anywhere.
What the next ten months looks like
Because of the transition to the continuous release model, the traditional timelines for the lifecycle of D2L’s existing in-market platforms has become accelerated. Here are the important dates you need to know:
As of this moment, both v9.4.1 and v10.0.0 of our Learning Suite are out of maintenance. All other more recent in-market releases are currently receiving full support.
That means that all the API contracts introduced by those platforms are currently deprecated. The principal contracts in question are:
- LE v1.0, v1.1
- LP v1.0, v1.1
- EP v2.0, v2.1
- LR v1.0
August 31, 2014
On August 31 of 2014, two sets of things will happen:
Firstly, v9.4.1 and v10.0.0 of our Learning Suite are out of support. This means that all the API contracts listed in the previous section move fromdeprecated to obsolete, and could get removed from all in-market releases at any time.
Secondly, v10.1.0 and v10.2.0 of our Learning Suite are out of maintenance. This means that all the API contracts that they introduced will become deprecated. The principle contracts in question there are:
- LE v1.2, v1.3
- LP v1.2, v1.3
- EP v2.2, v2.3
January 4, 2015
On January 4 of 2015, the v10.1.0 and v10.2.0 versions of our Learning Suite will pass out of support. At this point, all the API contracts listed in the previous sections will become obsolete.
What this means to you
You should be planning now to move, within the next half a year, from any of these legacy API contracts up to the API contracts introduced with at leastthe v10.3.0 version of the Learning Suite.
Luckily this should not be onerous for you, thanks to D2L’s careful policies around API evolution.
API contracts strive to be supersets. Each successive API contract included, as much as possible, all the API calls from the previously released API contracts. This means that for nearly all your API calls in your integration, all you’ll need to do is increment the API version number in the call to the latest ones provided by your back-end service, and do minimal testing to look for regressions.
API contracts strive to be backwards compatible. All the Learning Framework API contracts released to this point have been minor releases and in nearly all cases have been fully backwards compatible with previous contract versions. Again, you can safely use the latest APIs provided by your back-end service, and do minimal testing to look for regressions.
There are a quite small number of APIs where fixes or improvements have introduced some backward incompatibility; however, even in these cases, the changes have been minimal. You can effectively prepare for your transition.