Skip navigation
All Places > Blackboard Developer Community > Blackboard Learn Developers > Blog > 2018 > October
2018
mkauffman

REST API Deprecation Process

Posted by mkauffman Oct 22, 2018

We've had questions come in regarding REST API v1 deprecation. The answers to these questions inline below:

 

 

   When it comes to V1 route deprecation what will be process of notifying the V1 route consumers?

 

   - What will be the notification process?

 

Deprecation of REST APIs take place only when a new version is released - the deprecation is noted on the API documentation page: https://developer.blackboard.com/portal/displayApi

 

 

   - How long will it take to completely remove once notified? 

 

Removal of deprecated REST APIs from product will take place minimally* one year after deprecation is noted in the API documentation.

*In extremely rare cases this removal may take place sooner than one year - if that is the case it will be noted in the above noted documentation.

 

 

   - Will the V1 routes be removed from existing BB Learn instance versions?

 

Deprecated APIs will continue to work with releases prior to the Learn version from which they are removed.

 

E.G.: API is deprecated in 3300.0 and removed in 3400.0 - the deprecated API will continue to work with all supported Learn versions prior to 3400.0.

 

   - If not, from which Blackboard instance version upwards will V1 routes be removed and when is it scheduled?

 

 

See above.

At the University of South Wales we are currently implementing Grades Journey, for anyone going through the same process you will be concentrating on two key areas of work, provisioning and extraction.

 

The first task for us was provisioning and successfully connecting to the Grade Journey API is the first stepping stone.

 

Documentation

The details on how to use the REST API are available here:

https://help.blackboard.com/Learn/Administrator/SaaS/Integrations/Student_Information_System/SIS_Integration_Types/Grades_Journey/RESTful_Web_Services_Implementation/REST_Interface_Specifications#authorization_OTP-3

 

Details

We are interested in generating a MAC code which is passed along with API calls, the documentation tells us how to achieve this:

 

To properly authenticate users, the trusted system must be able to generate a valid MAC (message authentication code) to send with the SSO request. This MAC is used to determine the integrity of an SSO request. The steps required to generate a secure MAC are as follows:

 

  1. Sort the parameters API Key, Timestamp alphabetically by parameter name.
  2. Concatenate the parameter values by the sorted parameter names into a single string.
  3. Append the Shared Secret to the string obtained from Step 2.
  4. Encrypt the string into a 16-byte string using the MD5 algorithm.
  5. Convert the 16-byte string into a 32-byte alphanumeric (hexadecimal) string to make it URL-friendly.

Access the Grades Journey Building Block settings / REST API Security Settings (Incoming Data Security) and set the following values:

code.png

C Sharp code

A simple example of taking the API Key, Shared Secret and UNIX timestamp in milliseconds and generating a MAC code. In alphabetical order the parameters are:

  • api key
  • timestamp

if you name these differently in the settings then adapt to match accordingly.

 

* This code has no tests, error checking and sits in the body of the main method but is only for reference

 

Edit / run this code sample here: Repl.it - AdorableSlushyIrc

 

using System;

 

using System.Security.Cryptography;

using System.Text;

using System.IO;

 

class MainClass {

 

  public static void Main (string[] args) {

   // Grades Journey Authorization

   // Example of generating a MAC key 

   // API key and secret are set within the Building Block

   string APIKey = "this_is_your_api_key";

   string secret = "no_one_knows_this";

   int validTimeMS = 10000;


   // Current timestamp in Milliseconds

   string currentTimestamp = DateTimeOffset.Now.ToUnixTimeMilliseconds().ToString();

   string timestampExpiry = (DateTime.Now).AddMilliseconds(validTimeMS).ToString();

   string concactString = string.Concat(APIKey, currentTimestamp, secret);


   // Encrypt

  MD5 md5 = new MD5CryptoServiceProvider();

  UTF8Encoding encoder = new UTF8Encoding();

  Byte[] encodedBytes = md5.ComputeHash(encoder.GetBytes(concactString));

  string MAC = BitConverter.ToString(encodedBytes).Replace("-", "").ToLower();

 

  Console.WriteLine("******************************");

  Console.WriteLine("MAC: " + MAC);

  Console.WriteLine ("Valid until: " + timestampExpiry);

  Console.WriteLine("******************************");

  }


}

The outcome is a MAC code that was created at 13:07:05 which is valid for 10 seconds:

 

******************************

MAC: 4ee273df794692bc6e890f4184271878

Valid until: 10/19/2018 13:07:15

******************************

 

You would then use this MAC when calling the gradable items API endpoint to provision grade columns. If the API returns any authentication errors it is possible to access the system logs and view details on the API call and debug the issue. If anyone is interested I can post details on calling the API in another post.

 

mkauffman

Leave Some Breadcrumbs

Posted by mkauffman Oct 12, 2018

This one is for B2 developers. All of our current supported Learn builds have a left-navigation menu that comes and goes as you shrink and grow the browser window. Try it. Go into a course and shrink the browser window. You'll see the navigation menu disappear. Now grow the browser window and mouse over the left side of the window. You'll see an arrow that lets you make the navigation menu visible again. But, if your B2 is displaying content on the course page, without the bbNG: pageHeader and bbNG:breadcrumbBar tags, the left-navigation menu will disapper and you will not be able to get it back. Unless you reload the page.

 

This B2 has a sample course tool link which works correctly. GitHub - mark-b-kauffman/bbdn-bblogbackb2: Demo the use of Logback to create log files.

 

Here's a video demonstration: Dropbox - 2018-10-12_16-08-30.UseBreadcrumbs.KeepTheNavMenu.mp4

 

Leave some breadcrumbs!

mkauffman

It's Only A Model

Posted by mkauffman Oct 12, 2018

Camelot (it's only a model) - YouTube

Ok, this is not a blog post about silly movies. I'm writing because of a recent occurrence of difficulty noticing/finding a very important piece of our REST API documentation, the .... wait for it.... Model. As described below reading through the API Models can help reduce the number of REST API calls you make and improve your experience with Blackboard Learn REST endpoints in general.

 

Here we go. When you visit a REST API, you'll see the following Response Example Value.

RESTAPI.ExampleValue.jpeg

All well and good. But! There is a lot of important information hiding under the greyed out Model link. See it? When you click on it, you see the following Model!

RESTAPI.Model.jpeg

 

You really want to read all of that because... way down in the text you'll read:

Since: 3300.9.0

user (

User):

The user associated with the membership.

Shown when adding the query parameter: "expand=user". And can be filtered with the "fields" query parameter, for example "filter=user.uuid,user.externalId".

Which means that you CAN get all of the information you'd like about users in a course when pulling course memberships, without making additional REST calls to the /users endpoint.

 

Be certain to check out the Models!