Key versioning concepts¶

The Brightspace API has flexibility built in to help it support a varied population of clients: API components present in a deployed LMS product version will present multiple component versions; this approach allows overlapped versions to facilitate the transition of client applications dependent upon a particular version of a feature set.

Product version

A deployed LMS service will have an overall version or brand (such as “20.20.1”) that represents the collection of features comprised within the overall, installed product release. This product version is not visible from within the API itself; rather, it implies the collective set of API component versions its API components can provide (see following).

API component

Each product component or tool installed in the service will have a set of actions it can support. These actions are grouped together into a set of routes, branching out from the /d2l/api root with a D2LPRODUCT string (for example, the /d2l/api/lp/1.23/users/whoami action is provided by the Learning Platform product component, identified by the lp D2LPRODUCT string).

API contract version

Each product component can provide its own versions of the routes it provides. These versions are of the major-minor type (“1.23”), and appear in the route with a D2LVERSION string (again, for example, the /d2l/api/lp/1.23/users/whoami action is provided by version 1.23 of the lp product component’s API contract).

Each product component may expose a set of experimental routes in a special unstable version namespace. For example, you might find an experimental version of the whoami action at /d2l/api/lp/unstable/users/whoami.

When a version number changes

We classify changes appearing in the API as either non-breaking or breaking.

• Non-breaking changes include pure additions to the API (additions of properties on resources returned from an action, accepting these resources with or without the property inbound to the server, or adding new resources or new actions). Non-breaking changes can also include the new appearance of properties within JSON structures, because we assume that clients use forgiving, not strict, parsing on the JSON they receive from Brightspace.

  Minor non-breaking changes or fixes will not change a product component’s API contract version number.

  More significant non-breaking changes can increment the minor component of the product component’s API contract version number (for example, from 1.23 to 1.24).

• Breaking changes include updates to the API (change of how a client calls an action, or what the action does) or deprecations (removing actions or resources).

  Breaking changes will prompt a change to the product component’s API contract major version number.

In the What’s in the Brightspace developer platform? topic we maintain a table summarizing the various version associations for each major product component.

Checking for version support¶

Most commonly, you’ll want to know if the deployed LMS service “supports your application”; that is, you’ll want to know if the product components in that service provide the right versions of the product component features you need to use. We recommend that the right time to verify this is when your application gets launched (if it’s short running), and if necessary with daily frequency (if it’s very long running). The steps to verify the service’s supported versions are quite light on bandwidth and performance.

Example. Suppose your application requires that the lp product component supports API version 1.23 actions, to perform basic user lookups. However, your application also requires API version 2.5 from the service’s ep product component, to gain access to ePortfolio artifacts. To test this, you would use the POST /d2l/api/versions/check action, providing a JSON block like this:

[
    {
        "ProductCode": "lp",
        "Version": "1.23"
    },
    {
        "ProductCode": "ep",
        "Version": "2.5"
    }
]

The service returns a JSON data block something like this:

{
   "Supported": true,
   "Versions": [
       {
           "ProductCode": "lp",
           "Version": "1.23",
           "Supported": true,
           "LatestVersion": "1.29"
       },
       {
           "ProductCode": "ep",
           "Version": "2.5",
           "Supported": true,
           "LatestVersion": "2.5"
       }
   ]
}

From the returned data you only need to examine the top-level Supported property to know if the complete set of your support requests are possible. If the top level Supported property is false, then you will need to look for the Supported properties in each composite included in the Versions array to find the product component that doesn’t meet your requirements.

See the API properties topic for more detailed information on the kinds of version verification actions you can take.

Dealing with deprecation¶

API contract versions are loosely coupled with the product component releases that introduce them. As a consequence, when a Learning Suite platform release gradually moves out of full support from D2L, the API contract version originating with that Learning Suite also gradually moves out of full support. To help customers move from an older API contract onto a newer one, the deprecation process happens gradually.

For more precise information on milestone dates for a Learning Suite platform release, please contact your organization’s approved support contact, or your account or partner manager.

Deprecation¶

When an Integrated Learning Platform release reaches the “End of Maintenance” milestone in its lifecycle, the Brightspace API contracts introduced with that release become deprecated. When we mark an API contract version for deprecation, this action has the following implications:

• It won’t receive prioritized support or attention: D2L 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.

• You should put a priority on planning the transition of all your work off the deprecated API contract.

Obsolescence¶

After a period of time in deprecation, D2L can plan to actively remove an API contract. This is most likely to occur when a Learning Suite platform release reaches the “End of Support” milestone in its lifecycle:

• Obsolete API contracts may have their access entirely removed from the back-end service, so that calling them could generate an error (most likely 404 Not Found).

• The API contract may remain in your platform release, but its presence can no longer be depended upon, and you should put a high priority on transitioning all your work away from the obsolete API contract.

EOL¶

End of Life¶

At any time after obsolescence, D2L can follow through to enact the removal of an API contract from its releases. This will happen when a Learning Suite platform feature or component reaches the “End of Life” milestone in its lifecycle:

• End of Life API contracts will have their access entirely removed from the back-end service, so that calling them will generate an error (most likely, 404 Not Found).

• The API contract will no longer remain in your platform release, and you should put a very high priority on transitioning away from any use of that removed End of Life API contract.

/d2l/api/lp/1.23/users/whoami

/d2l/api/lp/1.24/users/whoami