Developer Platform (December 2024)

API Properties (versions, logging, authentication)

«  Integrating with the Integrated Learning Platform UI   ·  [   home  ·   reference  ·   community   |   search  ·   index   ·  routing table   ·  scopes table   ]   ·  Tools  »

Attributes

Activities

AVAILABILITY_T

Availability dates can be used to restrict an activity’s access in different ways, classified by type. We use the term AVAILABILITY_T to stand in for an appropriate integer value.

Availability type

Value

AccessRestricted

0

SubmissionRestricted

1

Hidden

2

Authentication

Auth.TokenInfo
{
    "Token": <string>
}
Access.UserAccess
{
   "UserId": <number:D2LID>,
   "HasAccess": <boolean>
}

Error Reporting

Errors.ProblemDetails

In some situations, when problems occur, the back-end service cannot return enough information using standard HTTP response codes alone. In these cases, the service may report errors using a JSON structure like this:

{
    "type": <string>,
    "status": <number>,
    "title": <string>,
    "detail": <string>,
    "instance": <string>
}

You can find more information about this structure format in Problem Details for HTTP APIs.

For more information about the status values generally returned by the Brightspace APIs and when those might happen, see Disposition and error handling in our topic on calling the API.

Logging

LOGLEVEL_T

Possible values, to describe the various levels of log message inspection. Each log level includes only logged events of that level, not events of any other level as well. We use the term LOGLEVEL_T to stand in for an appropriate value.

Log level

Debug

Info

Warn

Error

Fatal
Logging.Message
{
    "LogMessageId": <string>,
    "LogLevel": <string:LOGLEVEL_T>,
    "MessageTimestamp": <string:UTCDateTime>,
    "ExceptionMessage": <string>,
    "MachineName": <string>,
    "ProcessName": <string>,
    "ProcessStartTime": <string:UTCDateTime>|null,
    "LoggerAssembly": <string>,
    "LoggerType": <string>,
    "ExceptionStackTrace": <string>|null,
    "ExceptionType": <string>,
    "DeveloperMessage": <string>,
    "StackTrace": <string>|null,
    "MessageGroupId": <number:D2LID>,
    "UserId": <number:D2LID>|null,
    "OrgId": <number:D2LID>|null,
    "OrgUnitId": <number:D2LID>|null
}
ExceptionStackTrace and StackTrace

If the caller requesting the log message asked to includeTraces, these properties could be populated with stack trace data; otherwise, they will be null.

Logging.MessageGroupSummary
{
    "LogMessageId": <string>,
    "LogLevel": <string:LOGLEVEL_T>,
    "DeveloperMessage": <string>,
    "LoggerAssembly": <string>,
    "LoggerType": <string>,
    "ExceptionAssembly": <string>,
    "ExceptionType": <string>,
    "ExceptionMessage": <string>,
    "MessageGroupId": <number:D2LID>,
    "MessageCount": <number>,
    "UserId": <number:D2LID>|null,
    "OrgUnitId": <number:D2LID>|null
}

Versions

Version.BulkSupportedVersionResponse

When you make a query about whether one or more product components support your provided versions, the framework responds with a JSON block like this:

{
    "Supported": <boolean>,
    "Versions": [ // Array of BulkSupportedVersionResponseItem blocks
         {
             "ProductCode": <string:D2LPRODUCT>,
             "Version": <string:D2LVERSION>,
             "Supported": <boolean>,
             "LatestVersion": <string:D2LVERSION>
         },
         {  <composite:BulkSupportedVersionResponseItem> }, ...
    ]
}

Note that the first Supported field in this block generally describes whether all of your check requests have indicated support – if any one of your check requests lacks support, then this first value will be false.

Version.ApiVersion

When you make a general query about what versions your service’s Brightspace API supports, you’ll get back an array of blocks that associated a product component code to a version:

{
    "Version": <string:D2LVERSION>,
    "ProductCode": <string:D2LPRODUCT>
}
Version.ProductVersions

Data structure to describe the various Brightspace API versions supported by a particular product component:

{
    "ProductCode": <string:D2LPRODUCT>,
    "LatestVersion": <string:D2LVERSION>,
    "SupportedVersions": [ // Array of D2LVERSION strings
        <string:D2LVERSION>,
        <string:D2LVERSION>,
        <string:D2LVERSION>, ...
    ]
}
Version.SupportedVersion

When you use the API to query about a product component’s support for a particular version, you’ll get a response block back like this, showing you not only whether the component supports your queried version, but also the latest version of the API that it does support:

{
    "Supported": <boolean>,
    "LatestVersion": <string:D2LVERSION>
}
Version.SupportedVersionRequest

When you use the API to query about a product component’s support for a particular version, you send a block like this in your POST body:

{
    "ProductCode": <string>,
    "Version": <string>
}

Actions

Authentication

Note that the following legacy ID-Key authentication actions are supported by the LP product component.

GET /d2l/auth/api/cancel

Cancel the authentication process.

Status Codes:
API Versions:

  • all – Route supported in all versions.

Return. Expect this action to simply return 403 Forbidden to signify that the calling application is not currently authenticated to use the Framework API.

GET /d2l/auth/api/token

Request an authentication token from the Learning System Framework API.

Query Parameters:

  • x_target (URL-encoded URL) – Trusted URL to which the service should redirect upon successful user authentication.

  • x_state (string) – Optional. Session state value the back-end service passes back to the trusted URL callback.

  • x_a (Application ID) – Unique Application ID issued by D2L for the calling client application.

  • x_b (Application Signature) – Application session signature: target URL (not URL encoded) signed with the application key.

  • type (string) – Optional. Client application type: mobile or not present.

Status Codes:
API Versions:

  • all – Route supported in all versions.

Input. This route supports the first stage in the legacy ID-key authentication process used to set up an authenticated calling context for further route invocations. Thus, unlike with other routes, you do not provide all the authentication parameters as with other REST API calls; instead, use the query parameters listed here, only.

Note

Your x_target query parameter must indicate the trusted URL you associated with your application record when you registered your application with D2L (or directly with your back-end service via the Manage Extensibility tool).

GET /d2l/api/lp/(version)/auth/soaptoken

Retrieve a SOAP services authentication token given an existing calling user context.

Parameters:
Query Parameters:

  • purpose (string) – Token type/request purpose for the underlying service’s token provider.

Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

Input. Your call must provide a query parameter identifying the purpose of the request (that is, the type of token you want to retrieve). For each token type the back-end service can provide, the administrator must have installed, confirmed, and enabled the appropriate component of the service:

Purpose string

Service must have …

“Respondus”

Respondus Integration Pack installed, configured, and enabled.

Return. Successful calls will retrieve a TokenInfo JSON data block wrapping a SOAP token string of the appropriate type for the current user context.

Logging

GET /d2l/api/lp/(version)/logging/

Retrieve all current log messages.

Parameters:
Query Parameters:

  • dateRangeStart (UTCDateTime) – Earliest log item to show.

  • dateRangeEnd (UTCDateTime) – Latest log item to show.

  • search (string) – Optional. Filter logs to those only including this search string.

  • logLevel (CSV of LOGLEVEL_Ts) – Optional. Filter logs to include particular levels of detail.

  • loggerAssembly (string) – Optional. Filter logs to those emitted by a named application assembly.

  • userId (D2LID) – Optional. Filter logs to those related to identified user.

  • messageGroupId (integer) – Optional. Filter logs to those in identified message group.

  • includeTraces (boolean) – Optional. If true, include execution traces in retrieved logs.

  • orgUnitId (D2LID) – Optional. Filter logs to those related to identified org unit.

  • bookmark (string) – Optional. Bookmark to use for fetching next data set segment.

Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

Input. You can use a bookmark query parameter as a paging offset, to indicate that the service should return the segment of results immediately following you bookmark.

You can use a variety of filter query parameters to narrow the result set to those log entries that match the associated filters. If you provide more than one filter query parameter, they are all logically ANDed together.

Return. This action returns a paged result set containing the resulting Message data blocks for the segment following your bookmark parameter (or the first segment occuring after your dateRangeStart parameter, if the bookmark is empty or missing).

Note

This action employs the LogMessageId property enclosed within the Message block as the paging control value. You can fetch the segment of results following any log message’s entry in the entire data set by passing that message’s LogMessageId property as the bookmark value.

GET /d2l/api/lp/(version)/logging/grouped/

Retrieve all current log arranged in message groups.

Parameters:
Query Parameters:

  • dateRangeStart (UTCDateTime) – Earliest log item to show.

  • dateRangeEnd (UTCDateTime) – Latest log item to show.

  • search (string) – Optional. Filter logs to those only including this search string.

  • logLevel (CSV of LOGLEVEL_Ts) – Optional. Filter logs to include particular levels of detail.

  • loggerAssembly (string) – Optional. Filter logs to those emitted by a named application assembly.

  • userId (D2LID) – Optional. Filter logs to those related to identified user.

  • messageGroupId (integer) – Optional. Filter logs to those in identified message group.

  • orgUnitId (D2LID) – Optional. Filter logs to those related to identified org unit.

  • bookmark (string) – Optional. Bookmark to use for fetching next data set segment.

Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

Input. You can use a bookmark query parameter as a paging offset, to indicate that the service should return the segment of results immediately following you bookmark.

You can use a variety of filter query parameters to narrow the result set to those log entries that match the associated filters. If you provide more than one filter query parameter, they are all logically ANDed together.

Return. This action returns a paged result set containing the resulting MessageGroupSummary data blocks for the segment for the segment following your bookmark parameter.

GET /d2l/api/lp/(version)/logging/(logMessageId)/

Retrieve identified log message.

Parameters:

  • version (D2LVERSION) – API version.

  • logMessageId (D2LID) – Log message ID.

Query Parameters:

  • includeTraces (boolean) – Optional. If true, include execution traces in retrieved logs.

Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

Return. This action returns a Message JSON block containing the data for the indicated log message.

Versions

You can take a number of different actions involving API versions, roughly divided into actions that address a particular platform component and those that address the back-end learning platform as a whole. Note that support for these actions is provided by the LP product component.

Note

You can make all of these calls anonymously.

If you’re using OAuth2, you do not need to provide an Authorization header (containing a bearer token) with your call.

If you’re using legacy ID-Key Authentication, you do not need to include the x_b and x_d query parameter values for these calls. If you do provide user ID and user signature query parameter values with these calls, you should ensure they are validly formed user tokens. This has the advantage of identifying the application making the call to these routes.

GET /d2l/api/(productCode)/versions/

Retrieve the collection of versions supported by a specific product component.

Parameters:

  • productCode (D2LPRODUCT) – Identifier for a Brightspace product component.

Status Codes:
API Versions:

  • all – Route supported in all versions.

Return. This action returns a ProductVersions JSON block containing the list of versions supported by the indicated product component.

GET /d2l/api/(productCode)/versions/(version)

Determine if a specific product component supports a particular API version.

Parameters:

  • productCode (D2LPRODUCT) – Identifier for a Brightspace product component.

  • version (D2LVERSION) – API version to query.

Status Codes:
API Versions:

  • all – Route supported in all versions.

Return. This action returns a SupportedVersion JSON block indicating if the provided product component supports the provided API version.

GET /d2l/api/versions/

Retrieve all supported versions for all product components.

Status Codes:
API Versions:

  • all – Route supported in all versions.

Return. This action returns a JSON array of ProductVersions blocks.

POST /d2l/api/versions/check

Determine the versions supported by the back-end’s Brightspace API.

JSON Parameters:
Status Codes:
API Versions:

  • all – Route supported in all versions.

Input. If you want to check the versions supported by a single product component, you provide only a single element in the array you pass.

Return. This action returns a BulkSupportedVersionResponse JSON block.

«  Integrating with the Integrated Learning Platform UI   ·  [   home  ·   reference  ·   community   |   search  ·   index   ·  routing table   ·  scopes table   ]   ·  Tools  »