Valence (September 2014)

Course content (content objects, ISBNs, tables of content)

«  Grades (grade objects, categories, values, schemes)   ·  [   home  ·   reference  ·   community   ·  index   ·  routing table   ·  modules   ]   ·  LTI management (links and tool providers)  »

Contents

Attributes

CONTENT_T

Course content come in two types: course modules and course topics; we use the term CONTENT_T to stand in for an appropriate integer value:

Content object type Value
Module 0
Topic 1
TOPIC_T

Course topic objects are grouped into a set of types and we use the term TOPIC_T to stand in for an appropriate integer value.

Content Topic type Value
File 1
Link 3
SCORM_2004 5 ^
SCORM_2004_ROOT 6 ^
SCORM_1_2 7 ^
SCORM_1_2_ROOT 8 ^

^ Reserved for future implementation

Content.ContentObject
IsLocked
Some SCORM content packages can support sequencing, locking the topic ordering. Content objects with this property set True don’t permit content re-ordering or navigating the content out of sequence.
Type
When you use an action that retrieves information from the service for a course’s content, you get back one of two types of ContentObject JSON blocks (as indicated in the ContentObject’s Type property). In modules, this property has the value 0; in topics, this property has the value 1.

Module.

{
    "Structure": [ <Content.ContentObject>, ... ],
    "ModuleStartDate": <string:UTCDateTime>|null,
    "ModuleEndDate": <string:UTCDateTime>|null,
    "ModuleDueDate": <string:UTCDateTime>|null,  // Added with LE v1.3 API
    "IsHidden": <boolean>,
    "IsLocked": <boolean>,
    "Id": <number:D2LID>,
    "Title": <string>,
    "ShortTitle": <string>,
    "Type": 0
}

Changed in version 1.3: ModuleDueDate property added to this structure with v1.3 of the LE API. If this property is present and not null, the content module has a due date. If the property is present with a non-null value, it contains a UTCDateTime.

Topic.

{
    "TopicType": <number:TOPIC_T>,
    "Url": <string>,
    "StartDate": <string:UTCDateTime>|null,
    "EndDate": <string:UTCDateTime>|null,
    "DueDate": <string:UTCDateTime>|null,  // Added with LE v1.3 API
    "IsHidden": <boolean>,
    "IsLocked": <boolean>,
    "Id": <number:D2LID>,
    "Title": <string>,
    "ShortTitle": <string>,
    "Type": 1
}

Changed in version 1.3: DueDate property added to this structure with v1.3 of the LE API. If this property is present and not null, the content topic has a due date. If the property is present with a non-null value, it contains a UTCDateTime.

Content.ContentObjectData

When you use an action to provide course content information, you use one of two types of ContentObjectData JSON blocks (and use the Type property to indicate which type it is):

Title
In LE API versions 1.0 through 1.2, this field may not be empty or null. Starting with LMS v10.2.0 (LE API v1.3), this field may not be empty, null, or consist only of white-space characters.
ShortTitle
In LE API versions 1.0 and 1.1, this field may not be empty, null, or consist only of white-space characters. Starting with LMS v10.1.0 (LE API v1.2), this field may be empty or null.
Type
In modules, this property has the value 0; in topics, this property has the value 1.
Url

In link-type topics (TopicType value 3), this property should be the URL you want to fetch when the user opens the link-type topic.

In file-type topics (TopicType value 1), this property should contain a new URL that is valid within the course offering’s content space and indicate where the system should place the file.

Module.

{
    "Title": <string>,
    "ShortTitle": <string>,
    "Type": 0,
    "ModuleStartDate": <string:UTCDateTime>|null,
    "ModuleEndDate": <string:UTCDateTime>|null,
    "ModuleDueDate": <string:UTCDateTime>|null,  // Added with LE v1.3 API
    "IsHidden": <boolean>,
    "IsLocked": <boolean>
}

Changed in version 1.3: ModuleDueDate property added to this structure with v1.3 of the LE API. If this property is present and not null, the content module has a due date. If the property is present with a non-null value, it should contain a UTCDateTime.

Topic.

{
    "Title": <string>,
    "ShortTitle": <string>,
    "Type": 1,
    "TopicType": <number:TOPIC_T>,
    "Url": <string>,
    "StartDate": <string:UTCDateTime>|null,
    "EndDate": <string:UTCDateTime>|null,
    "DueDate": <string:UTCDateTime>|null,  // Added with LE v1.3 API
    "IsHidden": <boolean>,
    "IsLocked": <boolean>
}

Changed in version 1.3: DueDate property added to this structure with v1.3 of the LE API. If this property is present and not null, the content topic has a due date. If the property is present with a non-null value, it should contain a UTCDateTime.

Content overview

Each course offering org unit can have a course overview consisting of a rich text description and an optional attachment.

Overview.Overview
{
    "Description": <composite:RichText>,
    "HasAttachment": <boolean>
}

ISBN

The ISBN actions support ISO 2108:2005 standard 10- and 13-digit ISBN numbers passed as strings in JSON blocks and HTTP query parameter values.

ISBN.IsbnAssociation

When the client uses actions that retrieve the association between an ISBN and an org unit, the service sends back data blocks that look like this:

{
    "OrgUnitId": <number:D2LID>,
    "Isbn": <string>,
    "IsRequired": <boolean>  // Optional. Added with LE v1.3 API
}

Changed in version 1.3: IsRequired property added to this structure with v1.3 of the LE API. If this property is present, it will be either true (to indicate that the content item is required for the org unit) or false (to indicate the content item is optional for the org unit).

ISBN.IsbnAssociationData

Client actions that provide new ISBN data to the service use a block like this:

{
    "Isbn": <string>,
    "IsRequired": <boolean>  // Optional. Added with LE v1.3 API
}

Changed in version 1.3: The IsRequired optional property added to this structure with v1.3 of the LE API. If this property is present, it must be either true (to indicate that the content item is required for the org unit) or false (to incidate the content item is optional for the org unit). False is the default value for this property, and if the property is not present, the back-end service assumes false.

Table of contents

ToC.TableOfContents

This is a nested structure. The TableOfContent comprises a list of Module blocks. Each Module block can contain a list of Topic blocks, and can contain a list of child Module blocks. Thus, each module can have a child that’s a topic, or another module, but topics are “leaf nodes”.

{
    "Modules": [ // Array of Module blocks
        {
            "ModuleId": <number:D2LID>,  // Added with LE v1.3 API
            "Title": <string>,
            "Modules": [ // Array of child Module blocks
                {
                    "ModuleId": <number:D2LID>,  // Added with LE v1.3 API
                    "Title": <string>,
                    "Modules": [ <ToC.Module>, ... ],
                    "Topics": [ <ToC.Topic>, ... ]
                },
                { <composite:Module> }, ...
            ],
            "Topics": [ // Array of Topic blocks
                {
                    "TopicId": <number:D2LID>,  // Added with LE v1.3 API
                    "Identifier": <string:D2LID>,
                    "TypeIdentifier": <string>,
                    "Title": <string>,
                    "Bookmarked": <boolean>,
                    "Unread": <boolean>,
                    "Url": <string>  // Added with LE v1.3 API
                },
                { <composite:Topic> }, ...
            ]
        },
        { <composite:Module> }, ...
    ]
}

Changed in version 1.3: ModuleId property added to this structure, appearing inside each Module block. If the property is present, and not null, the property contains a D2LID for the module.

Changed in version 1.3: TopicId property added to this structure, appearing inside each Topic block. If the property is present, and not null, the property contains a D2LID for the module. Note that this property contains the same identifier as the Identifier property, but formatted as a JSON number rather than as a string.

Changed in version 1.3: Url property added to this structure, appearing inside each Topic block. This carries the same value as appears in a ContentObjectData block: for link content topics, it’s the content link; for file content topics, it’s the URL in the course content space for the file data.

Actions

DELETE /d2l/api/le/(version)/(orgUnitId)/content/modules/(moduleId)

Delete a specific module from an org unit.

Parameters:
  • version (D2LVERSION) – API version.
  • orgUnitId (D2LID) – Org unit ID.
  • moduleId (D2LID) – Module ID.
Status Codes:
  • 200 OK – Action succeeded.
  • 400 Bad Request – Content object with provided module ID is not a module.
  • 403 Forbidden – No permission to delete course content.
  • 404 Not Found – Module ID not found in provided org unit, or org unit not found.
API Versions:
  • 1.1-Deprecated as of LMS v10.4.0.
  • 1.2+ – Route first appears in LMS v10.1.0.
DELETE /d2l/api/le/(version)/(orgUnitId)/content/topics/(topicId)

Delete a specific topic from an org unit.

Parameters:
  • version (D2LVERSION) – API version.
  • orgUnitId (D2LID) – Org unit ID.
  • topicId (D2LID) – Topic ID.
Status Codes:
  • 200 OK – Action succeeded.
  • 400 Bad Request – Content object with provided topic ID is not a topic.
  • 403 Forbidden – No permission to delete course content.
  • 404 Not Found – Topic ID not found in provided org unit, or org unit not found.
API Versions:
  • 1.1-Deprecated as of LMS v10.4.0.
  • 1.2+ – Route first appears in LMS v10.1.0.
GET /d2l/api/le/(version)/(orgUnitId)/content/modules/(moduleId)

Retrieve a specific module for an org unit.

Parameters:
  • version (D2LVERSION) – API version.
  • orgUnitId (D2LID) – Org unit ID.
  • moduleId (D2LID) – Module ID.
Status Codes:
  • 200 OK – Action succeeded.
  • 400 Bad Request – Content object with provided module ID is not a module.
  • 403 Forbidden – No permission to view course content.
  • 404 Not Found – Module ID not found in provided org unit, or org unit not found.
API Versions:
  • 1.1-Deprecated as of LMS v10.4.0.
  • 1.2+ – Route first appears in LMS v10.1.0.

Return. This action returns a ContentObject JSON data block of type Module.

GET /d2l/api/le/(version)/(orgUnitId)/content/modules/(moduleId)/structure/

Retrieve the structure for a specific module in an org unit.

Parameters:
  • version (D2LVERSION) – API version.
  • orgUnitId (D2LID) – Org unit ID.
  • moduleId (D2LID) – Module ID.
Status Codes:
  • 200 OK – Action succeeded.
  • 400 Bad Request – Content object with provided module ID is not a module.
  • 403 Forbidden – No permission to view course content.
  • 404 Not Found – Module ID not found in provided org unit, or org unit not found.
API Versions:
  • 1.1-Deprecated as of LMS v10.4.0.
  • 1.2+ – Route first appears in LMS v10.1.0.

Return. This action returns a JSON array of ContentObject data blocks (can by either Module or Topic type blocks).

GET /d2l/api/le/(version)/(orgUnitId)/content/root/

Retrieve the root module(s) for an org unit.

Parameters:
Status Codes:
API Versions:
  • 1.1-Deprecated as of LMS v10.4.0.
  • 1.2+ – Route first appears in LMS v10.1.0.

Return. This action returns a JSON array of ContentObject data blocks of type Module.

GET /d2l/api/le/(version)/(orgUnitId)/content/topics/(topicId)

Retrieve a specific topic for an org unit.

Parameters:
  • version (D2LVERSION) – API version.
  • orgUnitId (D2LID) – Org unit ID.
  • topicId (D2LID) – Topic ID.
Status Codes:
  • 200 OK – Action succeeded.
  • 400 Bad Request – Content object with provided topic ID is not a topic.
  • 403 Forbidden – No permission to view course content.
  • 404 Not Found – Topic ID not found in provided org unit, or org unit not found.
API Versions:
  • 1.1-Deprecated as of LMS v10.4.0.
  • 1.2+ – Route first appears in LMS v10.1.0.

Return. This action returns a ContentObject JSON data block of type Topic.

GET /d2l/api/le/(version)/(orgUnitId)/content/topics/(topicId)/file

Retrieve the content topic file for a content topic.

Parameters:
  • version (D2LVERSION) – API version.
  • orgUnitId (D2LID) – Org unit ID.
  • topicId (D2LID) – Topic ID.
Status Codes:
  • 200 OK – Action succeeded.
  • 400 Bad Request – Content topic is not a file.
  • 403 Forbidden – No permission to view course content.
  • 404 Not Found – Topic ID not found in provided org unit, or org unit not found, or content topic’s file not found.
API Versions:
  • 1.3+ – Route first appears in LMS v10.2.0.

Return. This action retrieves the underlying file for a file content topic.

POST /d2l/api/le/(version)/(orgUnitId)/content/modules/(moduleId)/structure/

Add a child module or topic to a specific module’s structure.

Parameters:
  • version (D2LVERSION) – API version.
  • orgUnitId (D2LID) – Org unit ID.
  • moduleId (D2LID) – Module ID for the parent module.
JSON Parameters:
 
  • varies – Varies (see input description).
Status Codes:
  • 200 OK – Action succeeded.
  • 400 Bad Request – Provided parent module ID does not identify a module, or invalid child topic data provided.
  • 403 Forbidden – No permission to create or edit course content.
  • 404 Not Found – Parent module ID not found in provided org unit, or org unit not found, or attempt to re-use existing file failed because existing file not found.
API Versions:
  • 1.1-Deprecated as of LMS v10.4.0.
  • 1.2+ – Route first appears in LMS v10.1.0.
  • 1.3+ – Route now returns properties of the created topic or module.

Input. You can use this action in several ways, depending on whether you’re attempting to add a child module, a child link topic, or a child file topic to an existing (parent) module.

Module. If you’re adding a child module to a parent module’s structure, you should provide a POST body containing a single part: a ContentObjectData JSON data block of type Module.

Link Topic. If you’re adding a child topic to a parent module’s structure that consists of a Link type topic (3), you should provide a POST body containing a single part: a ContentObjectData JSON data block of type Topic. In this case, the Url property in the data block points to the resource you want the link to point to.

File Topic. If you’re adding a child topic to a parent module’s structure that consists of a File type topic (1), you should provide a multipart/mixed post body with two parts (as with the simple file upload process): the first, a ContentObjectData JSON data block of type Topic; the second, the file attachment data itself that you want to store in the org unit’s content area.

When providing a file, the ContentObjectData’s Url property must contain a URL that’s valid for the current org unit’s content space, identifying the path to the new file, and the name the new file will have in the content space (typically something like /content/enforced/orgunit_id-org_id/newfilename).

If you want to re-use a file in the org unit’s content space, you can provide a ContentObjectData block that points to the existing file, indicate a File topic type (1), and not post any attached file data.

Return. On success, this action returns a JSON data block containin the properties for the content object you’ve created:

  • If you’re adding a module, this action returns a ContentObject JSON data block of type Module.
  • If you’re adding a file or link type topic, this action returns a ContentObject JSON data block of type Topic.
POST /d2l/api/le/(version)/(orgUnitId)/content/root/

Create a new root module for an org unit.

Parameters:
JSON Parameters:
 
Status Codes:
  • 200 OK – Action succeeded.
  • 403 Forbidden – No permission to create or edit course content.
API Versions:
  • 1.1-Deprecated as of LMS v10.4.0.
  • 1.2+ – Route first appears in LMS v10.1.0.
  • 1.3+ – Route now returns properties for the created root module.

Return. This action returns a ContentObject JSON data block of type Module.

PUT /d2l/api/le/(version)/(orgUnitId)/content/modules/(moduleId)

Update a particular module for an org unit.

Parameters:
  • version (D2LVERSION) – API version.
  • orgUnitId (D2LID) – Org unit ID.
  • moduleId (D2LID) – Module ID.
JSON Parameters:
 
Status Codes:
  • 200 OK – Action succeeded.
  • 400 Bad Request – Invalid module data provided, or module ID provided does not identify a module.
  • 403 Forbidden – No permission to create or edit course content.
  • 404 Not Found – No such module found in org unit, or org unit not found.
API Versions:
  • 1.1-Deprecated as of LMS v10.4.0.
  • 1.2+ – Route first appears in LMS v10.1.0.

Input. Note that you cannot use this action to affect a module’s existing Structure property.

PUT /d2l/api/le/(version)/(orgUnitId)/content/topics/(topicId)

Update a particular topic for an org unit.

Parameters:
  • version (D2LVERSION) – API version.
  • orgUnitId (D2LID) – Org unit ID.
  • topicId (D2LID) – Topic ID.
JSON Parameters:
 
Status Codes:
  • 200 OK – Action succeeded.
  • 400 Bad Request – Invalid topic data provided, or topic ID provided does not identify a topic.
  • 403 Forbidden – No permission to create or edit course content.
  • 404 Not Found – No such topic found in org unit, or org unit not found.
API Versions:
  • 1.1-Deprecated as of LMS v10.4.0.
  • 1.2+ – Route first appears in LMS v10.1.0.

Input. Note that you can use this action to change a topic’s Url property, but if it changes the new URL must be a valid one for the org unit’s content store (the service makes no check that the URL actually points at anything useful, however). You cannot use this action to provide new file data for an existing topic.

Content overview

GET /d2l/api/le/(version)/(orgUnitId)/overview

Retrieve the overview for a course offering.

Parameters:
Status Codes:
API Versions:
  • 1.5+ – Route first appears in Learning Environment v10.4.0.

Return. This action returns a Overview JSON data block containing the course offering overview’s details.

GET /d2l/api/le/(version)/(orgUnitId)/overview/attachment

Retrieve the overview file attachment for a course offering.

Parameters:
Status Codes:
  • 200 OK – Action succeeded.
  • 403 Forbidden – No permission to retrieve course offering overview or overview attachment.
  • 404 Not Found – Course has no overview set, or course has no overview attachment, or cannot find attachment file.
API Versions:
  • 1.5+ – Route first appears in Learning Environment v10.4.0.

Return. This action returns a file stream containing the course offering’s overview attachment.

ISBN

DELETE /d2l/api/le/(version)/(orgUnitId)/content/isbn/(isbn)

Remove the association between an ISBN and org unit.

Parameters:
  • version (D2LVERSION) – API version.
  • orgUnitId (D2LID) – Org unit ID.
  • isbn (string) – ISBN.
Status Codes:
API Versions:
  • 1.2+ – Route first appears in LMS v10.1.0.
GET /d2l/api/le/(version)/content/isbn/(isbn)

Retrieve all the org units associated with an ISBN.

Parameters:
  • version (D2LVERSION) – API version.
  • isbn (string) – ISBN.
Status Codes:
API Versions:
  • 1.2+ – Route first appears in LMS v10.1.0.

Return. This action returns a JSON array of IsbnAssociation data blocks specifying all the org units associated with the provided ISBN.

GET /d2l/api/le/(version)/(orgUnitId)/content/isbn/

Retrieve all ISBNs associated with an org unit.

Parameters:
Status Codes:
API Versions:
  • 1.2+ – Route first appears in LMS v10.1.0.

Return. This action returns a JSON array of IsbnAssociation data blocks specifying all the org units associated with the provided ISBN.

GET /d2l/api/le/(version)/(orgUnitId)/content/isbn/(isbn)

Retrieve the association between a ISBN and org unit.

Parameters:
  • version (D2LVERSION) – API version.
  • orgUnitId (D2LID) – Org unit ID.
  • isbn (string) – ISBN.
Status Codes:
API Versions:
  • 1.2+ – Route first appears in LMS v10.1.0.

Return. This action returns a IsbnAssociation JSON data block specifying the association between an org unit and an ISBN.

POST /d2l/api/le/(version)/(orgUnitId)/content/isbn/

Create a new association between an ISBN and an org unit.

Parameters:
JSON Parameters:
 
Status Codes:
API Versions:
  • 1.2+ – Route first appears in LMS v10.1.0.

Return. This action returns a IsbnAssociation JSON data block for the newly created association.

Table of contents

GET /d2l/api/le/(version)/(orgUnitId)/content/bookmarks

Retrieve a list of topics that have been bookmarked.

Parameters:
Status Codes:
API Versions:
  • 1.1-Deprecated as of LMS v10.4.0.
  • 1.2+ – Route first appears in LMS v10.1.0.

Return. This action returns a JSON array of Topic ToC entries.

GET /d2l/api/le/(version)/(orgUnitId)/content/recent

Retrieve a list of the most recently visited topics.

Parameters:
Status Codes:
API Versions:
  • 1.1-Deprecated as of LMS v10.4.0.
  • 1.2+ – Route first appears in LMS v10.1.0.

Return. This action returns a JSON array of Topic ToC entries.

GET /d2l/api/le/(version)/(orgUnitId)/content/toc

Retrieve the table of course content for an org unit.

Parameters:
Status Codes:
API Versions:
  • 1.1-Deprecated as of LMS v10.4.0.
  • 1.2+ – Route first appears in LMS v10.1.0.

Return. This action returns a TableOfContents JSON block.


«  Grades (grade objects, categories, values, schemes)   ·  [   home  ·   reference  ·   community   ·  index   ·  routing table   ·  modules   ]   ·  LTI management (links and tool providers)  »