Getting Started With REST

Document created by scott.hurrey on Jan 29, 2016Last modified by rh0068002 on Jan 24, 2019
Version 21Show Document
  • View in full screen mode

Get Started with REST

Blackboard offers a suite of education technology tools, both software and hardware. REST stands for Representational State Transfer. It is a lightweight, flexible web service architecture that allows HTTP commands to be sent to Web Applications without unnecessary overhead. We provide specific examples and tutorials about using Blackboard REST APIs, particularly when a workflow is more complicated. For more general questions about REST and using REST APIs, see any of the numerous tutorials available online. Most commonly used resources include:

 

Before You Get Started

Blackboard offers lots of tools to help you develop an application, plugin, or other integration for use with Blackboard products like Blackboard Learn and Blackboard Collaborate. The most important ones are your accounts with these sites:

  • Blackboard Developer Portal is where you register applications so they can work with Blackboard products. It's also where you get your own key and secret that you need to authenticate your application with Blackboard products.
  • Blackboard Developer Community is where you learn to develop with Blackboard products, get the latest news, and discuss with other Blackboard integrators.

Note that the Developer Portal and Developer Community require separate accounts.

 

Register as a Blackboard Developer

Blackboard Learn REST integrations begin at the Developer Portal. This is where you register REST Applications and get the ID, key, and secrets. In the portal, you can see which client systems are using the integrations. Signing up is free, and you can develop your integration at no cost. There may be cost involved in deploying your integration, but before that happens, you'll have to speak with us. To discuss deploying your application, please contact us at developers@blackboard.com.Before you can authenticate your project with Blackboard applications, you need to be a registered Blackboard developer.To register as a Blackboard developer:

  1. Go to https://developer.blackboard.com/ and select Sign Up. Read and agree to the terms and conditions.
  2. Provide your email address, a password, your first name and last, and select the checkbox to prove you are human.
  3. Select Create Account and you're on your way.

For more information about the Developer Portal please see What is the Developer Portal: Developer Registration and Application Management.

 

Join the Community

The Blackboard developer community is the best place to find more information about integrating your project with Blackboard products. You will benefit from the community most by joining in.To register in the Blackboard developer community:

  1. Go to Blackboard Developer Community and select Register.
  2. If your organization is a Blackboard client or partner organization and you have a Behind the Blackboard login, select Behind the Blackboard Login. Otherwise, select Community Site Login.
  3. Enter your email address to receive a link via email.
  4. In your email's inbox, find the email sent by Blackboard. You might have to check your spam or junk folder. The email's subject is something like Blackboard Community: Email Validation. Select the link in your email. You will be taken to a registration page.
  5. In the registration page, complete all the required fields and select Create Account.

 

What Blackboard Application Do I Need?

Your Blackboard-compatible application can work with one or more of Blackboard's tools. How you build an integration with Blackboard software and hardware depends on which tools you want to integrate with. The tools you'll want to use depend on what you want to do.

 

I want to programmatically...You'll need to...
add files, text, and the like to Blackboard Learn
  1. authenticate with Blackboard Learn via REST API
  2. check out our Learn REST API reference
bulk add users to Blackboard Learn
  1. authenticate with Blackboard Learn via REST API
  2. check out our Learn REST API reference
set up video conference sessions
  1. authenticate with Blackboard Collaborate via REST API
  2. check out our Collaborate REST API reference
invite users to video conference sessions
  1. authenticate with Blackboard Collaborate via REST API
  2. check out our Collaborate REST API reference
get a list of users who attended a video conference session
  1. authenticate with Blackboard Collaborate via REST API
  2. check out our Collaborate REST API reference

Get Development Instances of Blackboard Applications

Blackboard makes available instances of Blackboard applications that you can use to build projects that integrate with Blackboard applications. Among others, we offer these popular developer instances. Blackboard does not charge a fee for entry-level use.

For more information about developer versions of Blackboard applications, see Developer Versions of Blackboard Applications in the community site (did you sign up yet?).

 

Developing with Blackboard Collaborate

Things are a little different for developing with Blackboard Collaborate. For more information, see the Collaborate REST API Reference and then email us at at developers@blackboard.com. We'll set you up with a key and secret for Blackboard Collaborate. Then read about how to use your key and secret to authenticate with Collaborate. The rest of the present topic pertains only to developing with Blackboard Learn.

 

Developing with Blackboard Learn

Go to the developer portal Register Developer Instances to the Cloud if this has not been done yet, and then Register Your Application to get a key and secret. Use your key and secret to authenticate with Learn.

 

 

Look at the Learn REST Reference

Check out the Learn REST API Reference. In particular, look at the range of endpoints available. Check the Since version for endpoint that interest you. This version number indicates the version since which the endpoint has been available. This way, you can make sure that your Blackboard server is is able to use it.

 

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 your application acquires an access token, it only needs to pass 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.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.

 

Configure an Instance of Learn to Work with Your Application

Once you have registered with the developer portal and built an integration, deploying to a Blackboard Learn SaaS instance is a simple step. The Blackboard Learn administrator that wants to use your integration needs the Application ID you got from the developer portal. The administrator will also need to create a Blackboard Learn user account with sufficient entitlements to associate with your integration. This gives the administrator full control over the entitlements used by your application. For more information on how to configure Learn, please see Managing REST Integrations in Learn: The REST Integrations Tool for System Administrators.

 

Glossary

TermDefinition
Application IDUnique identifier for the application used to integrate with the Blackboard Learn REST Services. Each unique integration should have its own Application.
Application KeyEach application is assigned a unique key. This is used to authorize REST API calls against Blackboard Learn.
Application SecretEach application is assigned a unique secret. This is used to authorize REST API calls against Blackboard Learn.
Access TokenA token is a unique string representing an implicit authorization granted by an OAuth 2.0 Service Provider.
CRUDCreate, Read, Update, Delete

More Information

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

3 people found this helpful

Attachments

    Outcomes