Developer Platform (January 2017)

What’s in the Brightspace developer platform?

«  Brightspace API Reference   ·  [   home  ·   reference  ·   community   ·  search   ·  index   ·  routing table   ]   ·  Core concepts  »

Contents

Brightspace includes all the APIs and tools that developers use to create valuable, integrated solutions for their customers. If you have used D2LWS APIs in the past, or are new to integrating with D2L’s products, then you can use the documentation on this site to understand the state-of-the-world for extensibility at D2L.

We’ve organized Brightspace’s developer platform into three general sets of materials:

Brightspace SDK. Provides access to the D2L Brightspace APIs, client libraries and tools, samples and walkthroughs.

Remote Plugin Service. Provides a user interaction extension point to a third-party service built on the IMS LTI (v1.0 and v1.1) standard.

Community Resources. Developers have access to the Developer Community of Practice (Dev CoP) which houses a set of resources including support forums, a developer blog, code samples, and the available developer support paths.

All our documentation is open and we are working to provide clear tools and programs. We host all our available open software in our Brightspace repository on GitHub.

Technology features

Web 2.0 integrated and decoupled. We’ve based our architecture upon the practices of Web 2.0 and cloud services that permit richly integrated apps, easy configuration, and operational independence. All access to our system is supported through HTTP and HTTPS calls.

ID-key Auth. Our three-legged authentication system ensures that we can transparently support all customer authentication scenarios involving your applications. Also, by ensuring that all API routes into an LMS occur within the acting context of a particular user login, service administrators can be confident that activating your application is a safe and constrained step to take.

REST/JSON standards. As a result of using RESTful APIs and JSON data structures, we provide a broad and well-supported technology base for our platform. You will find many off-the-shelf tools you can use to help simplify your work. Additionally, we provide open-source library wrappers for a number of languages with an emphasis on prioritizing the more sophisticated authentication steps of your application’s interaction with an LMS.

IMS LTI standards. As a result of building our Remote Plugin Service on top of the IMS LTI standard, we provide third-parties with a way to integrate their services with the Learning Service’s user experience in a standardized way incorporating robust, tool-to-tool trust. Additionally, the Remote Plugin Service automates the configuration of the integration for deployment to a variety of Learning Environment extension points (content, org unit homepages) and makes it easy for LTI Tool Providers to provide LTI-defined functionality and extend that functionality using the Brightspace APIs in concert.

Extensibility Areas. Our continually expanding suite of APIs provide access to a variety of technical functionality:

Area Notes
Org and structural Retrieve and update organizational structure, course lists, user information, and more
Content View and create content components and resources for a course
Assignments and grades Facilitate assignment and assessment-related features
Social Access to ePortfolio Collections, Artifacts, and activities of electronic portfolios

Current release changes

Our Brightspace ILP in continuous delivery provides the following features and changes as of January 2017.

API deprecation and obsolescence. With this release, the versions of our product component API contracts introduced with the following specific product components become (or remain) deprecated. While you can still call the routes in these contracts on the Learning Suites that have historically supported them, you should plan to migrate to the new API contracts available on your back-end service with due priority.

  Code Deprecated API contracts or services Obsolete API contracts or services
Learning Platform lp 1.4 1.3 and older
Learning Environment le 1.4 1.3 and older
Learning Repository lr   1.1 and older
ePortfolio ep 2.4 2.3 and older
D2L Web Services (SOAP) d2lws all versions  

Warning

We are also serving notice that the API contracts introduced with the Learning Suite v10.3.0 will be obsolete in late 2016, and after April of 2016, support for those API contracts will be by priority given only to those clients who have signed a support extension agreement for v10.3.0.

Brightspace API properties. With version 10.5 of Brightspace, we have enhanced the ID-key authentication system to allow web and native applications to pass session state through the request for user tokens on to the callback trusted URI using a new x_state parameter.

This can help maintain state between the token request and the token callback; D2L recommends that, if you use this parameter, you use it for something akin to a single-use, time-limited unguessable string as a “session key”; your application’s back-end can store state associated with this session key and use it to (for example), help mitigate the risk of cross-site request forgery attacks on the x_target callback URL.

If you make use of this parameter, you should realize that the user agent can see and manipulate it. Therefore, you should:

  • Take care that the value is unguessable and opaque
  • Minimize the lifespan of the value to reduce the possible impact of having this value escape outside one particular auth workflow
  • Always validate that the value passed back to the trusted URL matches an expected value

Learning Environment. Version 10.6.9 of the Learning Environment includes these improvements:

  • Added NotificationEmail property to DropboxFolder structures to contain a list of email addresses to notify when a user submits to a dropbox.

Version 10.6.8 of the Learning Environment includes these improvements:

  • Added routes to support Grade exemptions.
  • In the unstable contract, added ActivityId properties to content topics and topics in the content table of contents, to indicate the underlying actvity behind a topic in content.
  • In the unstable contract, added the ordinal sort order of topics and modules in the content table of contents, as well as start and end date information, to facilitate better presentation of the table of contents tree.

Version 10.6.7 of the Learning Environment includes these improvements:

  • The route in the User Progress family of API route which allow a user to retrieves the aggregate count of completed and required content topics in an org unit for a particular orgUnit has been promoted out of the unstable contract into the LE 1.19 API Contract.
  • The route in the Grades family of API routes which allow a user to retrieve a list of final grade valudes for the current user for a list of orgUnits have been promoted out of the unstable contract into the LE 1.19 API Contract.

Version 10.6.6 of the Learning Environment includes these improvements:

  • The routes in the myUpdates family of API routes which allow a user to query how many actionable items the users has for a particular orgUnit or a list of orgUnits have been promoted out of the unstable contract into the LE 1.18 API Contract.
  • The routes in the myEvents family of API routes allow a user to query what calendar events they have for a certain time range, either for a particular orgUnit or a list of orgUnits have been promoted out of the unstable contract into the LE 1.18 API Contract.

Version 10.6.5 of the Learning Environment includes these improvements:

  • When you fetch a content topic, its descriptive properties now point at the properties of the underlying, referred-to object (i.e. the title of the content topic will reflect the title of the underlying, referred-to object). This applies when you fetch content topics both by module structure and by topic ID.

    This also applies when you update or create a topic; the properties you set will get set on the underlying, referred-to object (if that object supports those properties).

Learning Platform. Version 10.6.7 of the Learning Platform product component includes these improvements:

  • The Code property has been added to the “fetch” form of the SectionData in the suite of Enrollment APIs.
  • The ShowInGrades property has been added to the “fetch” form of the Role in the suite of User APIs.

Version 10.6.6 of the Learning Platform product component includes these improvements:

  • The properties HomeUrl and ImageUrl in the Enrollment.OrgUnitInfo structure have been promoted into the LP 1.14 API contract.

Version 10.6.5 of the Learning Platform product component includes these improvements:

  • Added routes and structures to support Data Export from LP 1.13 API contract.

Previous changes. You can find details about previous platform releases on the history topic page.

Versions and migration

All API routes to an LMS component are versioned, and include a version negotiation process. This process allows your applications to gracefully adapt to the product components that a customer has active. Additionally, it lets D2L maintain overlapping API versions in a particular product installation, giving your application’s development a way to transition to new features along with your customers, gradually.

The following table shows the association between various product versions and the Brightspace APIs and services they offer. Each table column shows, for a major LMS platform release version:

  • The earliest and latest supported API contract versions provided either by an individual product component along with that product component’s release version (first four rows), or by the overall Learning Suite release version (ext APIs).

    Where a product component introduces a new API contract with a minor platform release version, this additional support gets noted (for example, LE added the 1.5 API contract as of LMS v10.4.3).

  • The version of support provided by an included service (Remote Plugin service, LTI support).

  Suite 10.6 Suite 10.5 (legacy) Suite 10.4 (legacy) Suite 10.3 (legacy)
Learning Platform (lp) 10.6.7+: 1.4*, 1.5 to 1.15
10.6.6: 1.4*, 1.5 to 1.14
10.6.5: 1.4*, 1.5 to 1.13
10.6.4: 1.4*, 1.5 to 1.10
10.6.3: 1.4*, 1.5 to 1.10
10.6.2: 1.4*, 1.5 to 1.10
10.6.1: 1.4*, 1.5 to 1.9
10.6.0: 1.4*, 1.5 to 1.8
10.5.5+: 1.4*, 1.5 to 1.8
10.5.4: 1.4*, 1.5 to 1.7
10.5.3: 1.4*, 1.5 to 1.6
10.5.0-2: 1.4*, 1.5
10.4.0+: 1.4*, 1.5 5.3.0+: 1.4*
Learning Environment (le) 10.6.9+: 1.4*, 1.5 to 1.21
10.6.8: 1.4*, 1.5 to 1.20
10.6.7: 1.4*, 1.5 to 1.19
10.6.6: 1.4*, 1.5 to 1.18
10.6.5: 1.4*, 1.5 to 1.15
10.6.4: 1.4*, 1.5 to 1.14
10.6.3: 1.4*, 1.5 to 1.14
10.6.0-2: 1.4*, 1.5 to 1.12
10.5.7+: 1.4*, 1.5 to 1.11
10.5.6: 1.4*, 1.5 to 1.10
10.5.5: 1.4*, 1.5 to 1.9
10.5.4: 1.4*, 1.5 to 1.8
10.5.3: 1.4*, 1.5 to 1.7
10.5.2: 1.4*, 1.5 t0 1.6
10.5.0-1: 1.4*, 1.5
10.4.3+: 1.4*, 1.5
10.4.0-2: 1.4*
10.3.0+: 1.4*
Learning Repository (LR) 10.6.0+: 1.2 10.5.0+: 1.2 10.4.8+: 1.2
10.4.0-7: 1.1!
6.3+: 1.1!
ePortfolio (ep) 10.6.0+: 2.4*, 2.5 10.5.0+: 2.4*, 2.5 10.4.0+: 2.4*, 2.5 4.3.0+: 2.4*
Extensibility (ext) 10.6.0+: 1.3 10.5.0+: 1.3 10.4.0+: 1.3 10.3.0+: 1.3
Remote Plugins (rp) 10.6.0+: RP service v1.5 10.5.0+: RP service v1.4 10.4.0+: RP service v1.4 10.3.0+: RP service v1.4
LTI support (lti) 10.6.0+: LTI v1.0 & v1.1.1 10.5.0+: LTI v1.0 & v1.1.1 10.4.0+: LTI v1.0 & v1.1.1 10.3.0+: LTI v1.0 & v1.1.1

Note

  • The Learning Environment product component released API contracts v1.16 through v1.18 with Brightspace release v10.6.6.

  • The Learning Platform product component released API contracts v1.11 through v1.13 with Brightspace release v10.6.5.

  • The Learning Environment product component released both API contracts v1.13 and v1.14 with Brightspace release v10.6.3.

  • The subsequent release after Suite 10.5.6 is 10.6.0.

  • Marked with *. As of Suite 10.5.6’s release (January 2016), the API contracts introduced with Learning Suite 10.3.0 have become deprecated. You should plan to move off these routes with all due priority.

  • Marked with !. As of Suite 10.4.8’s release, the Learning Repository (LR) product component’s v1.1 contract is obsolete, and replaced by the v1.2 contract.

  • As of Suite 10.4.7’s release (January 2015), the API contracts introduced with all versions of the Learning Suite prior to 10.3.0 have become obsolete: they may or may not still be present on your back-end service, and will not receive any support by D2L. You should move off the routes in these contracts immediately.

  • Extensibility APIs tie to the overall Learning Suite release version.

  • Remote Plugins tie to the overall Learning Suite release version. Remote Plugin course-builder and widget types were added before the rp product component appeared in a version block, prior to Learning Suite v10.1.0.

    Remote Plugin support indicates the Remote Plugin service version supported by the Learning Suite (that is, the types of Remote Plugin builds supported, and so forth).

  • LTI support indicates the LTI standard version supported by the Learning Suite

Program features

Tools and community. We intend to provide an expanding list of tools to assist you in developing and managing your relationship with D2L; for example, using our Keytool service you can easily register your application and retrieve the necessary Application ID and Key values you will need to authenticate with an installed LMS.

Additionally, we provide a Developer Community of Practice that supports you in a number of different ways depending on your needs.

Distributing applications with the Partner Program. Our relaunched partner program provides access to all the tools you need for success in deploying and commercializing your application or service, including levels that offer support, training, and partner business plans. For more information on partner benefits, check out our Partner Program home page.

Support

We provide support for Brightspace extensibility through a number of channels, depending upon the nature of your issue or question. See the list of available Support Paths in the Developer Community of Practice site.

«  Brightspace API Reference   ·  [   home  ·   reference  ·   community   ·  search   ·  index   ·  routing table   ]   ·  Core concepts  »