Getting Started With REST

Document created by scott.hurrey on Jan 29, 2016Last modified by scott.hurrey on Jan 29, 2018
Version 13Show Document
  • View in full screen mode

Blackboard is excited to announce the release REST APIs. These APIs are the preferred method of integration moving forward, although Building Blocks and the SOAP Web Services will continued to be supported.

 

 

Blackboard Learn SaaS is delivered continuously, and therefore regular updates will be made, both to the platform, as well as to the available REST APIs. As this is the case, we will continuously update the supporting documentation. Blackboard Learn Self- and Managed-Hosted will only receive REST updates on major releases.

 

 

 

Glossary

 

TermDefinition
REST

REST (or Representational State Transfer) is a lightweight, flexible Web Service architecture that allows HTTP commands to be sent to Web Applications without unnecessary overhead.

Developer PlatformThe tools, web sites, and documentation that correspond to the developer experience.
Developer Portal

Web Site used by Developers to register for an account and manage applications, keys, and secrets.

Application ID

Unique identifier for the application used to integrate with the Blackboard Learn REST Services. Each unique integration should have its own Application.

Application Key

Each application is assigned a unique key. This is used to authorize REST API calls against Blackboard Learn.

Application Secret

Each application is assigned a unique secret. This is used to authorize REST API calls against Blackboard Learn.

Access Token

A token is a unique string representing an implicit authorization granted by an OAuth 2.0 Service Provider.

CRUDCreate, Read, Update, Delete

 

The Blackboard Developer Platform

 

A Developer Platform is more than APIs. The platform is really about the experience the Developer has when learning and integrating with your APIs. One major component of the Developer Platform is the Developer Portal. This is where the Developer goes to register as a developer, register Applications to obtain the Application ID, Key and Secret, and peruse the Swagger-based API Documentation.

 

 

The Developer Platform also includes the Blackboard REST Developers community site. This is where all of the official documentation, discussion forums, blogs, and other social features live. There is also Sample Code on GitHub, Developer Outreach activities, like DevCon and ListServs, and new -- and perhaps most notably -- free, self-service sign up to eliminate unnecessary barriers to writing integrations. .

 

 

 

Developer Portal

 

All REST Integrations begin at the Developer Portal. This is where the Developer can sign up for an account, create REST Applications, and gather corresponding IDs, Keys, and Secrets, and even see what client systems are using the integrations. Signing up is free and easy, and you can develop your integration at no cost.

 

 

Depending upon how and where you plan to deploy your integration, there may be some cost involved. If you have any questions, please contact us at developers@blackboard.com. For more information about the Developer Portal, how to use it, and where to find it, please see What is the Developer Portal: Developer Registration and Application Management.

 

 

 

Configuring Learn

 

Once the developer has registered with the developer portal and built an integration, deploying to a Blackboard Learn SaaS instance is a simple step performed by the Administrator for the individual system that requires use of it. The administrator only needs the Application ID and a Blackboard Learn account to associate that application ID to. This gives the administrator full control over the Entitlements that the application has.

 

 

For more information on how to configure Learn, please see Managing REST Integrations in Learn: The REST Integrations Tool for System Administrators.

 

 

Authentication/Authorization

 

Authentication for REST Integrations follows the OAuth 2.0 RFC Standard. Essentially, every developer has a unique key and secret associated with each application they create. They make an HTTP Post to the API requesting client_credentials, which returns an authorization token that grants the application access to the Learn REST API for one hour. This token is then passed in subsequent REST calls until such time that the token expires. This can be done either with Basic Authentication or, as of Blackboard Learn 3200.7 in SaaS or Q4 2017 for self- and managed-hosted clients, using Three-Legged OAuth.

 

 

 

Calling Services

 

 

Once an access token is acquired, it is a simple as passing that token as a Bearer token in the Authorization header of your API calls. Review the authentication documentation in the above section for an overview, or find more specific details on the available API endpoints and APIs on the Developer Portal's Swagger API document.

 

As the list of supported APIs continues to grow, always check that document. Be sure to check the @Since annotation for each entry, as this will denote whether the API is available on your current build of Learn.

In its current implementation, Blackboard Learn REST APIs does not support Cross-Origin Resource Sharing (CORS). To learn about this and see an example to workaround this with Angular2, see the blog entitled Cross-Origin Resource Sharing; or Why I Can't Use AJAX with Learn APIs.

 

Application Development Workflow

 

The following diagram illustrates the workflow to go from a non-REST developer to having a working REST implementation.

 

 

More Information

 

We will continue to add new examples, tutorials, and code samples, so make sure to check these links regularly.

 

Attachments

    Outcomes