Tag Archives: devcon

REST and be thankful

This post’s title is a tribute to the highest point on a road in Scotland, where weary travellers would pause for breath (see this site). Today I am reflecting on the long journey that Blackboard has taken in its use of APIs and interface hooks and what the release of the new REST API means for developers.

One of the strengths of Blackboard’s Learn product has been the fact that developers could extend it using Blackboard’s Java APIs. This has led to a host of third party tools (including many free, open source solutions)  which add new functionality or address gaps in the interface (see the building blocks catalogue and the OSCELOT projects site). This has not been the easiest space to work in – despite repeated requests, many of the APIs remain undocumented or flagged as private – even though there is no other way to achieve the outcomes. Worse, the underlying data model suffers from an early decision to separate functions exposed in the user interface, from more administrative features (such as managing users, courses and enrolment records via a feed a student record system). This means that there are actually two classes representing most actors – e.g. blackboard.data.user.User and blackboard.admin.data.user.Person. The associated loaders use different parameters making the whole process more complicated/tedious than it needs to be. Extensions using these APIs and the associated tag libraries result in a tightly integrated solution that looks and feels just like the rest of Blackboard. That’s good, but as the code runs on the Blackboard server, there is a risk attached. As we see Blackboard’s preferred architecture moving from a self-hosted model to the cloud (in some cases adopting a multi-tenancy approach) then the ability to alter the core code becomes less attractive to the vendor.

Blackboard’s second foray into this area was to expose a series of SOAP web services. Whilst used by some clients, they are clunky and not popular with developers. They too suffer from incomplete documentation. Indeed they are so tardy that one developer (Andrew Martin from Newcastle) actually wrote alternative SOAP and REST frameworks, earning a Blackboard Developer’s Award in 2008.

Fast forward to 2016 and Blackboard finally unveiled their long-awaited REST APIs. Or at least the first few (see https://developer.blackboard.com/portal/displayApi). Initial impressions are good. They are using Swagger to document them, making it much easier to get started. They have also given a lot of thought to the end points with GET(get), POST (create), PATCH (update) and DELETE (delete) methods used consistently. As a slight aside, Blackboard are working on a similar set of REST APIs for their Collaborate product. That’s great but it looks like they were developed without talking to the Learn folks as they use slightly different method names (e.g. PUT rather than PATCH). Hopefully that discrepancy can be resolved before they are made public.

Calls use an OAuth token to authenticate. Each web application requires a unique key and secret, which the developer registers via Blackboard’s new Developer portal and then a Blackboard sys admin registers on their system. In this first implementation each app just has one key, I think it is likely that in later iterations it will be possible for developers to generate a unique key for each institution that chooses to deploy the app, allowing greater granularity of access control and reducing the risk of a man in the middle attack.

Blackboard’s Scott Hurrey and Mark O’Neil were both very keen for attendees to use the new API. To help, they have developed a series of examples on GitHub in a range of languages, including Python, Java, C Sharp and Ruby. The REST API is now included in the latest Blackboard Learn release (2016 Q2 – albeit flagged as ‘technical preview’) and in their Vagrant-based Developer Virtual Machine.

What does the mean for developers? The REST examples released to date are all external tools – designed to pull data from Blackboard Learn, possibly manipulating it and then pushing it back. This seems to be part of a co-ordinated move to “encourage” third party code to stay off the core Blackboard servers. Whilst sensible enough for commercial integrations, this is not such good news for in-house solutions or people developing extensions designed to run completely within Blackboard.

The new Blackboard Ultra lacks many of the extension points/hooks available to developers in previous versions of Learn (e.g. it won’t let you define new course control panel tools). There was one session suggesting that you could craft special LTI links using template variables and custom parameters which point at a building block to get round this  (LTI is still supported in Ultra) but this is at best a kludge. Even uploading code as a building block will require assistance from Blackboard.

In summary there is a lot to be thankful for if a set of REST APIs will meet your needs. These appear better thought out and better documented than ever before. If however your needs can only be met by code running Blackboard server-side, then things might get trickier in the future. It seems flexibility is being sacrificed for stability and security. Only time will tell how wise a move this is.