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.
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 Platform||The tools, web sites, and documentation that correspond to the developer experience.|
Web Site used by Developers to register for an account and manage applications, keys, and secrets.
Unique identifier for the application used to integrate with the Blackboard Learn REST Services. Each unique integration should have its own Application.
Each application is assigned a unique key. This is used to authorize REST API calls against Blackboard Learn.
Each application is assigned a unique secret. This is used to authorize REST API calls against Blackboard Learn.
A token is a unique string representing an implicit authorization granted by an OAuth 2.0 Service Provider.
|CRUD||Create, 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. .
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. (Note: We refer to any application that makes REST API calls to a Blackboard Learn system as a REST Application. A REST Application could be a web application running on a server, an app running on your phone, etc.)
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 email@example.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.
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 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.
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.
We will continue to add new examples, tutorials, and code samples, so make sure to check these links regularly.