Using curl to access the Blackboard REST API

30 Jun

So you have access to a shiny new instance of Blackboard, either at your institution or using the Blackboard AMI on AWS, and you want to write a tool using the Blackboard REST API, where do you even start?

Step One - Get curl

The easiest way to get started and explore the Blackboard REST API is to use curl. If you’re on a mac or linux machine, you should be already set to go. Just open a command prompt and type “curl” then <enter>, and should see something like the following

$ curl curl: try 'curl --help' or 'curl --manual' for more information

If you don’t see that, or you’re on windows, then you might need to install curl first. For this, Google is your friend, but you could give curl for windows a go to start with.

Now that you’ve confirmed that curl works, you can proceed to…

Step Two - Setting up a Blackboard Developer Account

If you haven’t done so already, you need to create a Blackboard Developer account. It’s free!

Go to https://developer.blackboard.com
Click on the Sign Up button.
Follow the instructions.

Once you’ve got an account you can go to…

Step Three - Creating an Application

Anything that connects to the Blackboard REST API needs to be authenticated and authorised. Normally the thing doing the connecting will be a Web Application or LTI Application, but it could be a mobile application (using three legged OAuth), or, as in this case, a command line tool. Curl.

Once you’ve logged-in to https://developer.blackboard.com using your shiny new account. Do the following.

Click on the + at the top of My Applications section
Fill in the form. Domains is the domain where your application will be hosted. Just put “localhost” in here if you’re experimenting with curl.
After you click Register application and generate API Key, you’ll be presented with some credentials. Make sure you record these somewhere, because you won’t be able to get them again without recreating the whole application.

Your job here is done, next is…

Step Four - Registering your application in Blackboard

Before your application (or curl), can connect to your Blackboard Instance, you need to register the app in Blackboard. To do this:

Navigate to System Admin → Building Blocks → REST API Integrations
Click Create Integration
Enter the Application ID obtained in Step Three.
Select the user which REST operations will be executed as (DO NOT use the administrator user).
The value of End User Access doesn’t matter for the purposes of this exercise.

Now, finally, you can go to…

Step Five - Getting a token from the API

To make requests you need an OAuth Bearer token, which you get by providing your Application Key and Application Secret from way back in Step Three. These are sent to the server in a POST request using HTTP Basic Auth (in an Authorization Header). The payload of the POST request must be the text “grant_type=client_credentials”.

The curl command is:

curl -k --user <application_key>:<secret> --data "grant_type=client_credentials" https://<bb-hostname>/learn/api/public/v1/oauth2/token

Where the items in bold are supplied by you.

The response will look something like the following (though not formatted so nicely):

{
    "access_token": "kmYecHHQNEWRs1YpMkfMybKH5K5uo1Hw",
    "expires_in": 2707,
    "token_type": "bearer"
}

Once you have the access_token, you can move on to...

Step Six - Actually fetching data

After all this setup, actually fetching data is pretty straightforward, if for example, you wanted to list all the courses on your Blackboard instance, you would use the following curl command.

curl -k -X GET -H "Authorization: Bearer <your access token>" https://<bb-hostname>/learn/api/public/v1/courses

Step Seven

Go Nuts!!

Wiley Fuller