Developer Platform (July 2017)

Typographical conventions for this reference.

«  Getting started   ·  [   home  ·   reference  ·   community   ·  search   ·  index   ·  routing table   ·  scopes table   ]   ·  Action requests  »

Contents

This reference documentation uses several typographical conventions to present actions, data types and structures.

REST-like action presentation

Each entry in the reference for a REST-like action consists of the HTTP method you’re expected to use, the route (portion of the URI to follow the Brightspace API service domain location), followed by any parameters the action requires.

Action properties information

Each action entry in the reference comes with a set of relevant property descriptions:

Parameters

Each action can have up to three sorts of parameters:

  • Simple (or route) parameters represent values in the route itself. You can distinguish route parameters in the reference documentation by values included in parentheses within the route itself:

    /d2l/api/lp/(version)/users/whoami
    
  • Query parameters are name-value pairs you pass as part of the action URL.

  • Form parameters are form-values you pass in a POST action.

Status codes
Each action typically returns 200 OK upon success, and other status codes for various unsuccessful results.
Versions

Each action shows version information for its presence in the API. If you see an API version number like 1.0+, this indicates you can depend on that action in a product component’s API from version 1.0 and forward. When an action’s behaviour changes, we note the version of the API supporting the new behaviour. If an action gets deprecated, we note the version where that has happened.

Also, each version entry in an route reference will indicate the product version (like LMS v9.4.1) where this change gets introduced. Alternatively, the notes might tie an API version to the release versions of one or more product components (like LE v10.0, LR v5.6).

Each action entry will also make relevant comments about what clients must provide as input to an action, and what they can expect to receive back from the server (if what they receive back is over and above the information related by the status codes).

JSON data presentation

The Brightspace API passes data back and forth using standard JSON notation (RFC 7159). These reference pages provide lots of examples to show you the kinds of JSON data blocks the framework expects to receive and return back to callers. In general, we use the term JSON data block to refer to a JSON document: we use the term block to reinforce that our APIs may return JSON arrays, objects, or in some cases simple JSON native data types (like JSON strings, numbers, true, false, or null).

Rather than provide a precise schema for the various JSON data blocks, we provide you with a “looks-like” sample that uses several conventions you should remember.

Comments

The JSON syntax does not support in-line comments, but you’ll see them in the examples in this reference. We include them to help elucidate the format of our structures so that the “real JSON” you see in the structure is as close as possible to the actual format you’d see over the wire. Our examples use /* ... */ for multi-line comments and // ... for single-line comments (for example, see the next section on arrays).

Saving space for embedded structures

Some of our JSON structures are quite complex (and some, theoretically non-terminating), and so we use several techniques to show you the structure in a way that isn’t going to appear in the data passed over the wire. In particular, this happens with the way we describe array properties.

We’ll document an array structure in one of these ways:

{
   "ArrayOfElements": [ // Array of Element blocks
       {
           "FieldOne": <string>,
           "FieldTwo": <number>
       },
       { <composite:Element> }, ...
   ],
   "ASimpleArrayOfStrings": [ // Array of strings
       <string>,
       <string>,
       <string>, ...
   ]
}

When you see the ellipsis in our examples, that’s an indication that the previous element can be repeated 0 or more times. However, as the ellipsis is not a valid JSON element, note that the server will actually send (or expect) a structure like something this (where all the items inbetween angle brackets are placeholders for those actual values):

{
   "ArrayOfElements": [
       { "FieldOne": "FieldValue", "FieldTwo": 1.0 },
       { "FieldOne": "FieldValue", "FieldTwo": 1.0 }
   ],
   "ASimpleArrayOfStrings": [ "One", "Two", "Three" ]
}

Field value placeholders

We use several ways to indicate general types of field values by writing placeholders, like this:

{
    "StringField": <string>,
    "BlackOrWhiteStringField": "Black|White",
    "NumberField": <number>,
    "NumberFieldReadAsLong": <number:long>,
    "BooleanField": <boolean>, // may only have the literal values 'true' or 'false'
    "ArrayField": [ <ArrayElement>, ... ],
    "CompositeField": { <composite:CompositeObject> }
}

Note that the last two of these indicate that they stand for an embedded array of ArrayElement items, and an embedded single instance of a CompositeObject composite field.

When we use the [<Type>] and {<composite:Type>} placeholder syntax, you should be able to find the Type being declared in the reference’s index, even if it’s defined close-by in the same reference topic.

Optional values

In some cases, JSON fields are null-able: you can provide values for them, or you can provide null (we present either null first, or the other value first, whichever results in a clearer description):

{
   "NullableNumber": <number>|null,
   "NullableString": null|<string>
}

Note that string properties differentiate between being provided as null or as empty:

{
   "NullString": null,
   "EmptyString": ""
}

In some cases, an embedded composite or array property might have to be fully included, or be null – in these cases, we’ll comment it as such.

In a few cases, the presence of a JSON field is actually optional: it can be present, or not present at all. In these cases, a comment will point this out. In this case, the OptionalStringField can have a string value, be null, or be missing entirely:

{
   "OptionalStringField": <string>|null  // Optional.
}

Commonly used fields

Several JSON fields are so common that we don’t fully expand them in our reference pages:

RichText

Whenever you see a {<composite:RichText>} field in a JSON example, that stands in for a composite block like this:

{
    "Text": <string:plaintext_version_of_text>,
    "Html": <string:HTML_formatted_version_of_text>|null
}
RichTextInput

Whenever you see a {<composite:RichTextInput>} field in a JSON example, that stands in for a composite block like this:

{
   "Content": <string>,
   "Type": "Text|Html"
}

System-specific data types

JSON fields are serialized as one of a number of simple types: number, string, boolean, array, object, or null. However, how you interpret these basic types varies depending upon context. In some cases, the Learning Framework passes you fields and expects you to interpret them in a particular way, and likewise when you provide data back to the framework.

The field types here pertain across the entire Brightspace API. Certain sections of the API will also have fields specific to their own actions (often binding enumerated integer values to semantic types), and in these cases the reference page for the API section contains definitions for these fields.

APIURL

A string value containing a fully formed URL you can use as the basis for another Brightspace API call related to the one that sent back this value (for example a NextPage API URL property sent back with a page of results).

Note that you still must attach authentication tokens to the API URL string before you can actually use it to make a call: this will require you to

  • Know what HTTP method you can use with this URL (in most cases, it will be an HTTP GET).
  • Be sure to use only the API path portion of the URL when forming the base string for authentication
CSV
Comma-separated list of values; for example, when passed as a query parameter, something like ?qparam=Val1,Val2,Val3.
D2LID

A value you should treat as a positive integer in the signed 64-bit number space (with values, therefore, ranging from 1 up to LONG_MAX). It’s intended as a unique identifier, within the context of the resource class it identifies (thus, a user’s UserID value should be unique with respect to the list of all users, but may be not be unique with respect to the list of all courses). Different routes in the API can expect D2LID values passed in subtly different ways:

  • In some routes, they should get passed as a JSON number type encoding a positive, 64-bit integer value.

  • In some routes, they should get passed as JSON strings which you’ll need to interpret as a positive, 64-bit integer value.

  • In some routes, they get passed as quoted parameter values, or as route parameters; in these cases, the value must be passed as an URL-safe unicode string value, but the service must be able to interpret it as a positive 64-bit integer value.

    If you provide a string not interpretable as a numeric value, it can bring unintended consequences, especially if the identifier is a parameter within the route itself (this can cause the service to misunderstand what route action you’re attempting, and assign your request to the wrong handler).

D2LPRODUCT

A string value that you should interpret as an identifier for one of the D2L product components installed in your back-end LMS:

ep – ePortfolio

le – Learning Environment

lp – Learning Platform

lr – Learning Repository

D2LVERSION
A string value that you should treat as a version specifier to indicate the version of the API you want to use. These version strings get built from a major and minor version number (for example: 1.0). Note that each component in the back-end learning platform you’re connecting to will have its own set of versions it can support.
GUID
UUID
A string value that you should treat as a 128-bit globally-unique identifier value. You should only need to read and compare, not generate, GUID values. Occasionally, some components will use GUIDs as unique identifiers instead of D2LID values.
LocalDateTime

A string value that you should treat as an ISO 8061 formatted date-time string in the user’s “local” time zone, with the addition of a three-digit millisecond value appended to the time value. The service requires that the time string use the format yyyy-MM-ddTHH:mm:ss.fff. Note that each element must occupy the specified number of digits, so leading zeroes are required.

For example, to indicate that someone created a comment 67 milliseconds after May 20, 2046, 08:15:30hr in the local timezone, you’d see a property value like this: "2046-05-20T08:15:30.067".

Replacement strings
The D2L integrated learning platform supports a macro facility called replacement strings. In some places in the LMS, a string used in the UI or to form an URL can include a special string of the form {rStringName} which gets expanded dynamically (either when the page gets rendered in the user’s browser, or when the user clicks on a link).
TenantID
A persistent, unique identifier for a Brightspace Tenant. Conceptually speaking, this maps closest to a historical D2L “Org”: that is, the bounding bundle of data and features that comprises one set of users and roles, one set of org unit nodes, one set of organization-level configuration, and so forth.
Timestamp
UnixTimestamp
An integer number value that you should treat as a standard Unix timestamp: the number of seconds since the Unix epoch (midnight, January 1st, 1970).
TimeZone
A string value representing a time zone in the IANA Time Zone Database.
UTCDateTime

A string value that you should treat as an ISO 8061 formatted date-time string in the Z (UTC+0) time zone, with the addition of a three-digit millisecond value appended to the time value (before the Z time zone specifier). The service requires that the time string use the format yyyy-MM-ddTHH:mm:ss.fffZ. Note that each element must occupy the specified number of digits, so leading zeroes are required.

For example, to indicate that someone created a comment 67 milliseconds after May 20, 2046, 08:15:30hr, EST (which is five hours behind UTC), you’d see a property value like this: "2046-05-20T13:15:30.067Z".

Application ID
Application Key
Application Signature
LMSID
LMSKEY

String values that form the basis of the Brightspace API’s authentication scheme.

The ID and Key form a symmetric key pair, where the ID gets sent with the message (API call) and the Key gets held privately and used to generate a Signature value sent with the message, to vouch for the message’s authenticity.

Each application using the Brightspace API must have its own Application ID-key pair, and can request from the back-end service a uniquely generated User ID/Key pair that corresponds to a single authenticated user known to the back-end service.

The back-end service also has an LMSID/LMSKEY pair that it uses for authenticated communication with D2L’s Keytool service in order to synchronize its list of known Application ID-key pairs.

«  Getting started   ·  [   home  ·   reference  ·   community   ·  search   ·  index   ·  routing table   ·  scopes table   ]   ·  Action requests  »