Skip to main content
pdf?stylesheet=default
Blackboard Help

REST Interface Specifications

Provisioning Interface

This interface will provision (i.e. create/update) gradable items and/or gradebook columns in Blackboard Learn.

Web Service Definition

Purpose Create / Update gradable items and/or gradebook columns.
Description Creates gradable items/gradebook columns from a supplied list of JSON data. Note that it will not create gradable items for a course if items have already been created. When creating a gradable item, it will create a gradable item using the parameters from the interface that can then be filled out manually to complete the set-up. The items will be created in the default or folder specified.
Endpoint /webapps/bbgs-GradeJourney-BBLEARN/app/REST/gradableItemsAPI
Method POST
Parameters Optional security parameters: apikey, timestamp, mac
JSON structure The JSON data must have the following elements with element names starting in lower case. Full definitions are in the table below.

course_id, item_type, name, instructions, anonymous, group, contentAreaName,available,colour,attempts,tracked,startDate,endDate, dueDate,poins,optionalData

Returns JSON List of status codes for the courses and assignments which were processed:

course_id = course id processed
name = the assignment name
status = OK or ERROR
message = text of the error message

The HTTP Status code will also be set as follows:

201 Created - on success

401 Unauthorized - if auth fails

412 Precondition Failed - if the course has already been populated with items, so if any course in the list fails, the rest will succeed but the 412 will be returned

500 Error - any other errors

Example Data [{"course_id":"course_001","item_type":"ASSIGNMENT","name":"assignment name","instructions":"assignment instructions.","anonymous":false,"group":false,"contentAreaName":"Subject Outline Tool Items", "available":true,"colour":"","attempts":1,"tracked":false,"startDate":"2013-04-07","endDate":"2013-04-07","dueDate":"2013-04-07","points":100.0, "extract":false, "optionalData":"key1\u003dvalue1:key2\u003d value2"}]
Example Response [{"name":"assignment name","message":"Course not found","status":"ERROR", "course_id":"course_001"}]

Provisioning Element Definition

Element Name Description Required Type and max size
Course_Id Course_id identifying the course to which this grade mode applies Yes String (256 chars)
Name Title of the gradable item Yes String (333 chars)
Item_type Type of gradable item to create

ASSIGNMENT – assignment

TEST – test

SURVEY – survey

DISCUSSION_BOARD – new gradable discussion board

WIKI – new gradable wiki

BLOG – new gradable blog

JOURNAL – new gradable journal

SELF_AND_PEER_TEST – new self and peer assessment

MANUAL_COLUMN – manual entry column

WEIGHTED_COLUMN – weighted column

TOTAL_COLUMN – total column

Note that that any new items in the future will need to be evaluated any will likely require changes to address.

Yes String (333 chars)
Instructions Instructions No String (2000 chars)
Anonymous True/false No Boolean (Default false)
Group True/false No Boolean (Default false)
ContentAreaName Default “Subject Outline Tool Items” No String (255 chars)
Available True/false No Boolean (Default false)
Colour Name or hex string No String (10 chars)
Attempts -1 for unlimited No Int (Default -1)
Tracked True/false No Boolean (Default false)
StartDate Display from date No Date*
EndDate Display until date No Date*
DueDate Due date No Date* Note that for variable dates, this value will not be passed as it is optional.
Points Points Possible No Float (Default 100.0)
GradeSchema Grade schema (this is the name as it exists in Bb). Note that this schema may have been created using the web service as available from the Grade Journey B2 or in the system. No String (333 chars)
SequenceNum Sequence display order number No Int
Extract Y/N – If yes, this column will be extracted from the extraction tool No Boolean (Default false)
Mapping For a weighted column, specify the mappings. Default is nothing so that it can be performed manually.

This should be the gradable item name/percentage pairs separated by a column. For example, Assignment 1=30,Test 1=30,Assignment 2=40

For a total column, specify just the columns that should be included in the total. For example, Assignment 1, Test 1, Assignment 2, Final Grade

No String (333 chars)
OptionalData Key/value pairs with each set of pairs separated by a colon, and key/values separated by an equal sign. For example: key1=value1:key2=value2 No String(2000 chars)

Grade Extract Interface

The purpose of this interface is to extract gradebook data for the SIS system.

Web Service Definition

Purpose The purpose of this interface is to extract gradebook data for the SIS system.
Description Extracts grade data as a list of JSON data.
Endpoint As specified by Endpoint
Method POST
Parameters Optional security parameters: apikey, timestamp, mac
JSON structure The JSON data must have the following elements with element names starting in lower case. Full definitions are in the table below.

Students: external_course_key,student_id,batch_uid,title,mark,grade

Footer: schedule_dt, record_count

Note that for a merged course, a separate export for each external_course_key will exist for each section.

Returns JSON List of status codes for the courses which were processed:

course_id = course id processed
status = OK or ERROR
message = text of the error message

Example Data [{"grades":[{"external_course_key":"course_001","student_id":"1234","batch_uid":"jstudent1","title":"Final External Grade","grade":"A","mark":160, "optionalData":"key1\u003dvalue1:key2\u003d value2"},{"external_course_key":"course_001","student_id":"4567","batch_uid":"jstudent2","title":"Administrative Override","grade":"","mark":"", "optionalData":"key1\u003dvalue1:key2\u003d value2"}],"footer":[{"schedule_dt":"2014-05-28 00:13:18.294","record_count":"2"}]}]
Example Response [{"external_course_key":"course_001","message":"All records processed succesfully","status":"SUCCESS"}]

Grade Extract Element Definition

Field Header Description Required Type and max size
EXTERNAL_COURSE_KEY The batch_uid for the course Yes String (256 chars)
STUDENT_ID The student id for the student Yes String (256 chars)
BATCH_UID The batch_uid for the student Yes String (256 chars)
TITLE Title of the grade column Yes String (333 chars)
MARK The mark Yes Float
GRADE The grade Yes String (32 chars)
EXTENDED_DATA Any optional data fields passed in No  
SCHEDULE_DT Schedule datetime Yes Datetime
RECORD_COUNT Record count Yes Float

Grade Schema Interface

The purpose of this interface is to create new gradebook schemas. This is optional.

Web Service Definition

Purpose The purpose of this interface is to create new gradebook schemas.
Description Creates grade schemas.
Endpoint /webapps/bbgs-GradeJourney-BBLEARN/app/REST/gradeSchemasAPI
Method POST
Parameters Optional security parameters: apikey, timestamp, mac
JSON structure The JSON data must have the following elements with element names starting in lower case. Full definitions are in the table below.

Title – The name of the schema.

Symbols – the code/value pairs for the schema.

OptionalData – any optional data to store with the schema.

Returns JSON List of status codes for the courses which were processed:

name = name of schema created
status = OK or ERROR
message = text of the error message

Example Data [{"title":"OverrideGrade","symbols":"SU\u003d99:US\u003d0","optionalData":"key1\u003dvalue1:key2\u003dvalue2"}]
Example Response [{"course_id":"","name":"OverrideGrade","status":"OK","message":"GradeSchema successfully created"}]

Grade Schema Element Definition

Field Header Description Required Type and max size
Title Title of the grading schema Yes String (333 chars)
Symbols Symbols in a list with (optional) lower bound No String (2000 chars)
OptionalData Key/value pairs with each set of pairs separated by a comma, and key/values separated by an equal sign. For example: key1=value1,key2=value2 No String (2000 chars)

Authorization

This interface will support two options for securing the API either or both may be used:

1. Secure REST API: uses a shared secret and a MD5 hash algorithm to generate a key which must be used to allow access to the REST endpoints.

2. IP Filter: Limits the servers which can communicate to the REST API to specific IP addresses. Multiple IP addresses can be listed separated by semi-colons. If IP addresses are limited, In order for the API test page to function, the BbLearn application server must be included in the list.

  • Shared Secret: the shared secret is a series of characters used in the encryption scheme to generate the hash. This secret must be used on the sending side to generate the hash value.
  • API Key: this is a set of characters which is passed along in the URL as a key value. It becomes encrypted into the hash and then is validated against the hash upon receipt.
  • TimeStamp Range: this value indicates the length of time the URL is valid. The timestamp is sent as part of the query string parameters and included in the hash. Upon receipt, the timestamp value is compared against the current timestamp and if the difference in time exceeds the range limit, the request is denied.
  • MAC Parameter: this value determines what query string parameter contains the MAC hash value.
  • API Key Parameter: this value determines what query string parameter contains the api key value.
  • IP Filter: a semi-colon delimited list of IP addresses that are allowed to access the API.

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