Skip navigation
All Places > Blackboard Developer Community > Blackboard Learn Developers > Blog > Author: 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:



   - 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.


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!


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.


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!



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

Since: 3300.9.0

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!

The Announcement! -->> Blackboard Deprecates SOAP Web Services


First - our forward looking statement applies to the information presented here*.


I'm writing this blog post because this week in our Blackboard Learn 9.1 Upgrade Cohort we mentioned our intent to announce deprecation of our SOAP Web Services near the end of this year. We also mentioned our intent to remove the SOAP Web Services from Learn within approx. a year of the deprecation announcement. There have been questions, specifically as to what is being deprecated. Here's a brief video giving the details about what will be deprecated: Dropbox - 2018-09-28_10-08-46BbSoapWSintentToDeprecate.mp4 Also, to be clear, the deprecation, and eventual removal, will only impact new versions of Learn – meaning that existing Learn releases will continue to support SOAP Web Services.


Finally, we need developers using SOAP Web Services to review the REST APIs now and contact us with any gaps that prevent them from migrating their SOAP-based application to a REST-based application. Reach out to us at


For additional context see:


*Statements regarding our product development initiatives, including new products and future product upgrades, updates or enhancements represent our current intentions, but may be modified, delayed or abandoned without prior notice and there is no assurance that such offering, upgrades, updates or functionality will become available unless and until they have been made generally available to our customers.

It's been a while, and this needs to be said. A few have asked about surfacing Building Block content in Ultra courses. You can't do that. B2 content can be surfaced in an Original course on an Ultra Nav-enabled system, but not in an Ultra course. The way into Ultra is LTI and REST. These offer advantages over B2 integrations in that you can code in any language, your integration is less dependent on the Learn server, and unlike a B2, the integration doesn't run in the same JVM as the Learn server. So, if you want to integrate with Ultra courses, check out REST , Blackboard's LTI Documentation and Basic Overview of How LTI works | IMS Global Learning Consortium


Not So Private

Posted by mkauffman Aug 13, 2018

By way of introduction, this an article about why you should migrate your B2 integration to LTI &/or REST.  With said, I started writing this article because of several B2 issues that have come up over the past year because of the B2's use of 'private' APIs. What is a private API? Simply stated, it's an API that a B2 can use, but it's not been published in our public Building Block API Documentation. Let's look at an example.


Some developers discovered, and have used this private API:



Our development team moved this Java API, and because it's private, they're under no obligation to inform anyone when they do so, or what they've done with it. Then, because it wasn't so private, B2s that used it fail in newer releases of Learn.


The good news is that we're developing and introducing REST APIs at a rapid pace, based on use case. If you have a use case that our APIs don't cover, you can submit submit your idea here. Our goal is to publish REST APIs that meet a majority of use cases, so you don't need to use a 'not so private' API.

Mark O'Neil, our Senior Product Manager, Developer Platform, and his team have been very busy in the past year! If you haven't been following the changes at Blackboard API Services, I'm writing this to give you a sense of what's new since last year around this time. Looking at our internal release notes and  the Learn SaaS Release Schedule | Blackboard Help I see that 3200.6 was released to client test systems near the end of June last year, and 3400.7 was released to client test on June 12th 2018. Given that, I see that we've released over 4 dozen new REST APIs in that period of time. Since the beginning of this year alone we've release many REST APIs that you will be interested in, including course assessments, LTI, course gradebook categories, and attempts. Head over to Blackboard API Services and check it out. And, a big thanks to Mark O'Neil and team!

Several partners have gotten stuck while attempting to update their Learn license. The help documentation needs an update for Windows. We're working on that.  In the meantime, if you're running Learn on a Windows server and run into issues updating your Learn license, do the following.


First, when updating the license, you need to refer to the section at the very bottom of the help documentation, "Upgrade a license without upgrading Blackboard Learn." Open a command prompt, as Administrator, and use the Blackboard Learn ServiceController script to stop all Blackboard services. Check that they are indeed stopped using the Windows Services control panel. Next, on your Windows server, do the following:


  • Rename the old license file: <path-to-blackboard>\blackboard\config\license\blackboard-license.xml to blackboard-license-OLD.xml
  • Copy the new license file to <path-to-blackboard>\blackboard\config\license\blackboard-license.xml
  • cd into the <path-to-blackboard>\blackboard\system\tooldefs\system\LicenseReplace directory
  • .\run-tool.bat  <path to blackboard>\blackboard\config\license\blackboard-license.xml

If you're attempting to build an LTI tool provider that supports Deep Linking aka Content Item Messaging and you see the following symptom described in Behind the Blackboard!


"LTI TP posts back to /webapps/blackboard/controller/lti/contentitem fails. When posting back to /webapps/blackboard/controller/lti/contentitem Learn fails with "The specified resource was not found, or you do not have permission to access it."


You can fix the issue by addressing two items in your code:

a) Blackboard Learn sends an optional "data" field with the LTI launch. Be certain you pass it back to Blackboard Learn.

b) The ContentItemSelection request sent to BB must be signed. You can check your signature with a tool like:

c) When checking the signature of the content received at your tool provider, unescape the content then create the signature to check. Do not sign the content before it has been unescaped. I.E. if you try to check the signature of content containing &quot; the signature will not match because Learn signed it when that character was represented as ".  The same holds in the other direction. Learn expects the content to be signed before the Tool Provider escapes the HTML. To be clear - we're talking about this type of HTML Escape/Unescape - Free Online HTML Escape / Unescape Tool -  Also, when you want to send an empty value to Learn, avoid null. Use "" instead.


Lastly, after calculating the signature, be certain to escape the content posted back to Learn, not encode it. As an example, for the " character use &quot; not %22.


The Partner that originally reported the issue got back to us and said they did the following above two items to their Tool Provider code to resolve it. In the meantime our automated processes created a known-issue article, then when the bug was closed by our LTI engineer as unable to reproduce it was set as being resolved in 3400.1.0. It's not a bug and functions as designed in all versions of Learn that content-item messaging is available.


Note: We've certified Blackboard Learn as an LTI Tool Consumer. If you have issues with your Tool Provider code and Blackboard Learn, our engineering team requests that you first certify your Tool Provider using the Learning Tools Interoperability Certification Suite | IMS Global Learning Consortium  - before bringing the issue to Blackboard.

tl;dr configuring REST in Learn and why doesn't my REST APP authorize with a Learn system that has a self-signed cert? Here's a video with a few pointers. Thanks for watching! Dropbox - RegardingSSLcertsAndRestIntegrationTool.mp4

I'm writing this to share how you can determine whether a given REST API is available in a particular Learn Release. I'm sharing this because we've had several queries, this should make it clear. If not, please do provide feed back in the comments section.


We'll use POST /learn/api/public/v1/courses/{courseId}/gradebook/columns as an example as this is a REST API one partner asked about.


Start by looking at and click the Explore button on the page. Look through the APIs and find course grades. Expand the API of interest by clicking on it.  In this case, POST /learn/api/public/v1/courses/{courseId}/gradebook/columns Notice Since: 3000.7.0 This is the build number that the POST REST API for gradebook columns was released. IMPORTANT: We never back port REST APIs. A cumulative update will not include a REST API release in a later build number. Example: 3000.0.9 will not include the POST gradebook/columns API.


Next, check this community post which explains how one can map recent Learn Releases (Q4 2016, ... etc.) to Build Numbers (3100.0.3, ... etc.).


The Build Number is what determines whether a REST API is available. The REST APIs are never backported via a cumulative update. We see that 3000.1.X is the build number for all Q2 2016 releases. The POST REST API for gradebook is not available there. The build number for all Q4 2016 releases and up is 3100 and greater. The POST REST API for grade book is available for all of these as we saw that is is available since 3000.7.0.


In conclusion, you should now be able to find out when any REST API became available for any QN YYYY release of Learn. For example, can you figure out which Learn releases now have the GET /learn/api/public/v1/courses/{courseId}/gradebook/columns/{columnId}/attempts API?


Happy New Year!




We've had many developers run into issues around site quotas and rate limits when moving their REST application into production use. To help smooth your transition to production we've published this document Developer Groups, Site Quotas, and Rate Limits  Please read it and give us your comments/questions. I won't say more here, the document should speak for itself! 

I'm writing this to show an easy way to test your REST API calls. This brief video shows you how to go about it. In the video we also answer a question about the Gradebook REST APIs. The question was whether the letter grade shows up in the REST call results when the letter grade is secondary. Watch to the video to find out, and learn how you can quickly troubleshoot REST API calls!


Update: We brought this to the attention of the development team with JIRA ticket API-1084. They've been clear in stating this is functioning as designed. Should you require different behavior, bring it to our attention on

This came up as a question from a developer, "How do I create a course in Learn that has a different course ID than the external Id? (The external Id is also often referred to as the batch UID.) The answer is to use the SIS Flat-File integration capability of Learn that is available on the System Administration tab. You can log in as a Learn administrator on a Learn system and follow along with the example given in this video: Create and Upload Courses Using a Flat File


For reference the documentation is given here:

Student Information System (SIS) | Blackboard Help

Create and Edit SIS Integrations | Blackboard Help

SIS Feed Files | Blackboard Help

Snapshot Flat File Examples | Blackboard Help

Course Examples | Blackboard Help

Hi All,


This topic comes up often regarding Learn versions, "How do I map the Learn release names to the build numbers?" One of our clients referred to finding the answer as "finding the secret decoder ring, or discovering the location of the Rosetta Stone." I'm writing this Blog post to share how I go about finding the answer.


It's simple. Just log in to Behind the Blackboard and use the search tool to look for the most recent release. I just entered "Q2 2017 CU4." There is no such release yet, but Cumulative Update 3 for Blackboard Learn, 9.1 Q2 2017 came up.  Now scroll down the page and you will see the Upgrade Paths listed, which also maps the Release Names to the Build Numbers as shown below. And there you have it, your very own Secret Decoder Ring mapping of Learn Release Names to Build Numbers.


Existing Blackboard Learn, Release 9.1 clients can upgrade from the following versions to 9.1 Q2 2017 CU3 (Build: 3200.0.3-rel.75+4185aa5)