Developer Platform (July 2017)

Lockers

«  Demographics (data types, fields, users and org units)   ·  [   home  ·   reference  ·   community   ·  search   ·  index   ·  routing table   ·  scopes table   ]   ·  Awards  »

Contents

Lockers are folders where users and groups can store files. When a user, or group, creates a folder in the locker or uploads a file into the locker, the folder structure gets rooted in a root folder named /. In the descriptions that follow of the routes that require you to provide a path, generally the root folder is assumed as part of the route (because the root / must always appear).

Each folder in the locker can contain files and other folders. All the items in a folder must have a unique name: a folder cannot contain both a file named Test and a folder named Test, nor can it contain two folders or two files named Test.

Items in the locker are identified not by ID, but by the path name to the item from the root folder. Path names use the slash as a name separator: the system understands a name with a trailing slash as a folder name; it understands a name without a trailing slash as a file name.

Lockers may have a maximum size for all contained items, and may also have a maximum size imposed on each individual item.

Warning

If you use the API to delete a folder from a locker, then the service will attempt to recursively delete all that folder’s contents as well.

Attributes

LOCKERITEM_T

The types of items that can appear in a user’s locker are organized into a discrete list. We use the term LOCKERITEM_T to stand in for an appropriate integer value.

Locker item type Value
Folder 0
File 1
Locker.Folder
{
    "Name": <string>,
    "Contents": [ <Locker.LockerItem>, ... ]
}
Locker.GroupLocker
{
    "HasLocker": <boolean>
}
Locker.LockerItem
{
    "Name": <string>,
    "Description": <string>|null,
    "Type": <number:LOCKERITEM_T>,
    "Size": <number:long>|null,
    "LastModified": <string:UTCDateTime>|null
}

Actions

DELETE /d2l/api/le/(version)/locker/myLocker/(path)

Delete a file or folder from the current user’s locker.

Parameters:
  • version (D2LVERSION) – API version.
  • path (string) – Locker path below the root folder.
Status Codes:
  • 200 OK – Action succeeded.
  • 400 Bad Request – Invalid path provided or attempt to delete root folder.
  • 403 Forbidden – Not permitted to modify locker, or not permitted to delete a child object contained in provided folder.
  • 404 Not Found – No such file or folder exists in locker.
API Versions:
  • 1.12+ – Route first appears in LMS v10.6.0.
  • 1.5-1.11Deprecated as of LMS v10.7.0.
  • 1.4-Obsolete as of LMS v10.7.0.

Input. Provide a locker path at the end of your action’s route. If the path ends in a trailing slash (/), this action seeks to delete the folder named before the slash. If the path ends in a name, this action seeks to delete the named file.

DELETE /d2l/api/le/(version)/locker/user/(userId)/(path)

Delete a file or folder from the provided user’s locker.

Parameters:
  • version (D2LVERSION) – API version.
  • userId (D2LID) – User ID.
  • path (string) – Locker path below the root folder.
Status Codes:
  • 200 OK – Action succeeded.
  • 400 Bad Request – Invalid path provided or attempt to delete root folder.
  • 403 Forbidden – Not permitted to modify locker, or not permitted to delete a child object contained in provided folder.
  • 404 Not Found – No such file or folder exists in locker, or no such user.
API Versions:
  • 1.12+ – Route first appears in LMS v10.6.0.
  • 1.5-1.11Deprecated as of LMS v10.7.0.
  • 1.4-Obsolete as of LMS v10.7.0.

Input. Provide a locker path at the end of your action’s route. If the path ends in a trailing slash (/), this action seeks to delete the folder named before the slash. If the path ends in a name, this action seeks to delete the named file.

Note

The calling user context may not use this route to modify another user’s locker. The provided userId in the route must be the calling user’s user ID.

GET /d2l/api/le/(version)/locker/myLocker/(path)

Retrieve a specific object from the current user’s locker.

Parameters:
  • version (D2LVERSION) – API version.
  • path (string) – Locker path below the root folder.
Status Codes:
API Versions:
  • 1.12+ – Route first appears in LMS v10.6.0.
  • 1.5-1.11Deprecated as of LMS v10.7.0.
  • 1.4-Obsolete as of LMS v10.7.0.

Input. Provide a locker path at the end of your action’s route. If your locker path ends in a trailing slash character (/), the service assumes you want to retrieve a locker folder; otherwise, it assumes you want to retrieve a file stored in a locker folder.

Return. If the action retrieves a folder, it returns a Folder JSON block. If the action retrieves a file, it returns a file stream.

GET /d2l/api/le/(version)/locker/user/(userId)/(path)

Retrieve a specific object from a provided user’s locker.

Parameters:
  • version (D2LVERSION) – API version.
  • userId (D2LID) – User ID for the owner of the locker.
  • path (string) – Locker path below the root folder.
Status Codes:
API Versions:
  • 1.12+ – Route first appears in LMS v10.6.0.
  • 1.5-1.11Deprecated as of LMS v10.7.0.
  • 1.4-Obsolete as of LMS v10.7.0.

Input. Provide a locker path at the end of your action’s route. If your locker path ends in a trailing slash character (/), the service assumes you want to retrieve a locker folder; otherwise, it assumes you want to retrieve a file stored in a locker folder.

Return. If the action retrieves a folder, it returns a Folder JSON block. If the action retrieves a file, it returns a file stream.

POST /d2l/api/le/(version)/locker/myLocker/(path)

Add a new file or folder to the current user’s locker.

Parameters:
  • version (D2LVERSION) – API version.
  • path (string) – Path below the root folder to a locker folder.
JSON Parameters:
 
  • FolderName (string) – Optional. Name of folder to create (see input description).
  • FileDescription (JSON composite) – Optional. File description block for new file (see input description).
Status Codes:
  • 200 OK – Action succeeded.
  • 400 Bad Request – Invalid path, or file or folder already exists, or provided file is too large.
  • 403 Forbidden – Not permitted to see or modify locker for current user context.
  • 404 Not Found – Current user has no locker.
API Versions:
  • 1.12+ – Route first appears in LMS v10.6.0.
  • 1.5-1.11Deprecated as of LMS v10.7.0.
  • 1.4-Obsolete as of LMS v10.7.0.

Input. You can use this action to add a new file or folder to the current user’s locker. The locker path you provide must be the name of a folder inside the current user’s locker, and thus your path parameter must end in a trailing slash (/).

Adding a folder. Your post body contents should contain a JSON block containing a simple string declaring the new folder’s name (no trailing slash is needed):

"NewFolderName"

Adding a new file. Your action should have a multipart post body containing file data and a file description JSON block:

{
    "Description": <string>,
    "IsPublic": <boolean>
}

You cannot use this action to replace an existing file with the same name; you may only provide files with names not yet contained in the locker.

This action limits the size of each individual file uploaded, and also respects the maximum locker size.

POST /d2l/api/le/(version)/locker/user/(userId)/(path)

Add a new file or folder to the provided user’s locker.

Parameters:
  • version (D2LVERSION) – API version.
  • userId (D2LID) – User ID for owner of locker.
  • path (string) – Path below the root folder to a locker folder.
JSON Parameters:
 
  • FolderName (string) – Optional. Name of folder to create (see input description).
  • FileDescription (JSON composite) – Optional. File description block for new file (see input description).
Status Codes:
  • 200 OK – Action succeeded.
  • 400 Bad Request – Invalid path, or file or folder already exists, or provided file is too large.
  • 403 Forbidden – Not permitted to see or modify locker for provided user.
  • 404 Not Found – User has no locker.
API Versions:
  • 1.12+ – Route first appears in LMS v10.6.0.
  • 1.5-1.11Deprecated as of LMS v10.7.0.
  • 1.4-Obsolete as of LMS v10.7.0.

Input. You can use this action to add a new file or folder to the identified user’s locker. The locker path you provide must be the name of a folder inside the user’s locker, and thus your path parameter must end in a trailing slash (/).

Adding a folder. Your post body contents should contain a JSON block containing a simple string declaring the new folder’s name (no trailing slash is needed):

"NewFolderName"

Adding a new file. Your action should have a multipart post body containing file data and a file description JSON block:

{
    "Description": <string>,
    "IsPublic": <boolean>
}

You cannot use this action to replace an existing file with the same name; you may only provide files with names not yet contained in the locker.

This action limits the size of each individual file uploaded, and also respects the maximum locker size.

Note

The calling user context may not use this route to modify another user’s locker. The provided userId in the route must be the calling user’s user ID.

PUT /d2l/api/le/(version)/locker/myLocker/(path)

Rename a folder in the current user’s locker.

Parameters:
  • version (D2LVERSION) – API version.
  • path (string) – Path below the root folder to the locker folder to rename.
JSON Parameters:
 
  • FolderName (string) – New name for the folder.
Status Codes:
  • 200 OK – Action succeeded.
  • 400 Bad Request – Invalid path, or invalid folder name, or attempt to rename root folder, or folder name already exists in parent folder.
  • 403 Forbidden – No permission to modify locker for current user context.
  • 404 Not Found – No such locker folder exists.
API Versions:
  • 1.12+ – Route first appears in LMS v10.6.0.
  • 1.5-1.11Deprecated as of LMS v10.7.0.
  • 1.4-Obsolete as of LMS v10.7.0.

Input. This action’s route must contain a path to a folder–the path must have a trailing slash (/).

PUT /d2l/api/le/(version)/locker/user/(userId)/(path)

Rename a folder in the provided user’s locker.

Parameters:
  • version (D2LVERSION) – API version.
  • userId (D2LID) – User ID for owner of locker.
  • path (string) – Path below the root folder to the locker folder to rename.
JSON Parameters:
 
  • FolderName (string) – New name for the folder.
Status Codes:
  • 200 OK – Action succeeded.
  • 400 Bad Request – Invalid path, or invalid folder name, or attempt to rename root folder, or folder name already exists in parent folder.
  • 403 Forbidden – No permission to modify locker for provided user.
  • 404 Not Found – No such locker folder exists.
API Versions:
  • 1.12+ – Route first appears in LMS v10.6.0.
  • 1.5-1.11Deprecated as of LMS v10.7.0.
  • 1.4-Obsolete as of LMS v10.7.0.

Input. This action’s route must contain a path to a folder–the path must have a trailing slash (/).

Note

The calling user context may not use this route to modify another user’s locker. The provided userId in the route must be the calling user’s user ID.

Lockers and groups

DELETE /d2l/api/le/(version)/(orgUnitId)/locker/group/(groupId)/(path)

Delete a file or folder from the locker of a group in the provided org unit.

Parameters:
  • version (D2LVERSION) – API version.
  • orgUnitId (D2LID) – Org unit ID.
  • groupId (D2LID) – Group IT.
  • path (string) – Locker path below the root folder.
Status Codes:
  • 200 OK – Action succeeded.
  • 400 Bad Request – Invalid path provided or attempt to delete root folder.
  • 403 Forbidden – Not permitted to modify locker, or not permitted to delete a child object contained in provided folder.
  • 404 Not Found – No such file or folder exists in locker, or no such org unit, or no such group.
API Versions:
  • 1.12+ – Route first appears in LMS v10.6.0.
  • 1.5-1.11Deprecated as of LMS v10.7.0.
  • 1.4-Obsolete as of LMS v10.7.0.

Input. Provide a locker path at the end of your action’s route. If the path ends in a trailing slash (/), this action seeks to delete the folder named before the slash. If the path ends in a name, this action seeks to delete the named file.

GET /d2l/api/lp/(version)/(orgUnitId)/groupcategories/(groupCategoryId)/locker

Determine if a locker has been set up for a group category within an org unit.

Parameters:
  • version (D2LVERSION) – API version
  • orgUnitId (D2LID) – Org unit ID.
  • groupCategoryId (D2LID) – Group category ID.
Status Codes:
API Versions:
  • 1.12+ – Route first appears in LMS v10.6.0.
  • 1.5-1.11Deprecated as of LMS v10.7.0.
  • 1.4-Obsolete as of LMS v10.7.0.

Return. This action returns a GroupLocker JSON block to indicate whether the group category has a locker set up.

GET /d2l/api/le/(version)/(orgUnitId)/locker/group/(groupId)/(path)

Retrieve a specific object from a provided group’s locker.

Parameters:
  • version (D2LVERSION) – API version.
  • orgUnitId (D2LID) – Org unit ID.
  • groupId (D2LID) – Group ID for a group entity within an org unit.
  • path (string) – Locker path below the root folder.
Status Codes:
API Versions:
  • 1.12+ – Route first appears in LMS v10.6.0.
  • 1.5-1.11Deprecated as of LMS v10.7.0.
  • 1.4-Obsolete as of LMS v10.7.0.

Input. Provide a locker path at the end of your action’s route. If your locker path ends in a trailing slash character (/), the service assumes you want to retrieve a locker folder; otherwise, it assumes you want to retrieve a file stored in a locker folder.

Return. If the action retrieves a folder, it returns a Folder JSON block. If the action retrieves a file, it returns a file stream.

POST /d2l/api/lp/(version)/(orgUnitId)/groupcategories/(groupCategoryId)/locker

Set up the locker for a group category within an org unit.

Parameters:
  • version (D2LVERSION) – API version.
  • orgUnitId (D2LID) – Org unit ID.
  • groupCategoryId (D2LID) – Group category ID.
Status Codes:
API Versions:
  • 1.12+ – Route first appears in LMS v10.6.0.
  • 1.5-1.11Deprecated as of LMS v10.7.0.
  • 1.4-Obsolete as of LMS v10.7.0.

Return. This action returns a GroupLocker JSON block to indicate the success or failure of this action.

POST /d2l/api/le/(version)/(orgUnitId)/locker/group/(groupId)/(path)

Add a new file or folder to the locker for a group in the provided org unit.

Parameters:
  • version (D2LVERSION) – API version.
  • orgUnitId (D2LID) – Org unit ID.
  • groupId (D2LID) – Group ID.
  • path (string) – Path below the root folder to a locker folder.
JSON Parameters:
 
  • FolderName (string) – Optional. Name of folder to create (see input description).
  • FileDescription (JSON composite) – Optional. File description block for new file (see input description).
Status Codes:
  • 200 OK – Action succeeded.
  • 400 Bad Request – Invalid path, or file or folder already exists, or provided file is too large.
  • 403 Forbidden – Not permitted to see or modify locker for the provided group.
  • 404 Not Found – Group has no locker.
API Versions:
  • 1.12+ – Route first appears in LMS v10.6.0.
  • 1.5-1.11Deprecated as of LMS v10.7.0.
  • 1.4-Obsolete as of LMS v10.7.0.

Input. You can use this action to add a new file or folder to the identified group’s locker. The locker path you provide must be the name of a folder inside the user’s locker, and thus your path parameter must end in a trailing slash (/).

Adding a folder. Your post body contents should contain a JSON block indicating the name of the folder to create:

"FolderName"

Adding a new file. Your action should have a multipart post body containing file data and a file description JSON block:

{
    "Description": <string>,
    "IsPublic": <boolean>
}

You cannot use this action to replace an existing file with the same name; you may only provide files with names not yet contained in the locker.

This action limits the size of each individual file uploaded, and also respects the maximum locker size.

PUT /d2l/api/le/(version)/(orgUnitId)/locker/group/(groupId)/(path)

Rename a folder in the locker for a group in the provided org unit.

Parameters:
  • version (D2LVERSION) – API version.
  • orgUnitId (D2LID) – Org unit ID.
  • groupId (D2LID) – Group ID.
  • path (string) – Path below the root folder to the locker folder to rename.
JSON Parameters:
 
  • FolderName (string) – New name for the folder.
Status Codes:
  • 200 OK – Action succeeded.
  • 400 Bad Request – Invalid path, or invalid folder name, or attempt to rename root folder, or folder name already exists in parent folder.
  • 403 Forbidden – No permission to modify locker for provided group.
  • 404 Not Found – No such locker folder exists.
API Versions:
  • 1.12+ – Route first appears in LMS v10.6.0.
  • 1.5-1.11Deprecated as of LMS v10.7.0.
  • 1.4-Obsolete as of LMS v10.7.0.

Input. This action’s route must contain a path to a folder–the path must have a trailing slash (/).

«  Demographics (data types, fields, users and org units)   ·  [   home  ·   reference  ·   community   ·  search   ·  index   ·  routing table   ·  scopes table   ]   ·  Awards  »