Basic concepts¶

Uploaded data and LMS item are two different things. Every item in the Learning Framework that’s backed by uploaded file data (an image, a video, a document) binds together two conceptual bits of information: the LMS object that represents the data in the Learning Framework (an eP Artifact, a Dropbox Submission Attachment), and the binary data that the user or client application provides for that object (the image or video or document data uploaded). It’s helpful to be conscious of this difference to grasp how the upload process works.

Authentication controls around the object ID. Because the binary data uploaded is essentially transitory until it gets bound into the Learning Framework, the LMS service focuses authentication controls around the acquiring and use of the upload key, and on the process of uploading the data itself. If a client can’t successfully attach the uploaded binary data to an LMS object, then eventually the service will purge the uploaded data from its temporary storage.

Authentication tokens on the request. In the HTTP request examples that follow, we have left out the mechanisms used for authenticating the request. You should consider that the authentication information will appear in your request, and be different depending on the authentication method you are using for your calls.

• If your client uses the OAuth2 authentication system, then the HTTP request will include your authentication bearer token in the Authentication header of the request, like in this example of the same call:

  PUT https://someLMShost.edu/d2l/api/lr/{version}/objects/?repositoryId={repo_ID_parm} HTTP/1.1
  Authentication: Bearer eyJ0eXAiOiJKV1Q...{rest of bearer token}
  Content-Type: multipart/form-data; boundary=xxBOUNDARYxx
  Content-Length: {PUT body length in bytes}
  

• If your client uses the legacy ID/Key-based authentication system, then the HTTP request URL will have your authentication tokens included as query parameters on the request URL, like the x_ parameters in this example:

  PUT https://someLMShost.edu/d2l/api/lr/{version}/objects/?x_t={timestamp}&x_a={app_id}&x_b={user_id}&x_d={user_sig}&x_c={app_sig}&repositoryId={repo_ID_parm} HTTP/1.1
  Content-Type: multipart/form-data; boundary=xxBOUNDARYxx
  Content-Length: {PUT body length in bytes}
  

Simple uploads¶

Simple (or “combined”) upload APIs support uploading data of a reasonably small size. These actions expect the client to provide all the file data with a single action.

The exact way that simple uploads get done varies with the product component, but there are two general types:

RFC1867 HTTP file upload

Profile image and LR package uploading gets done using the simple POST form file upload described in RFC 1867.

Upload to Learning Repository. Here’s an example showing what the actual HTTP request looks like for a simple upload of a new Learning Repository package:

PUT https://someLMShost.edu/d2l/api/lr/{version}/objects/?repositoryId={repo_ID_parm} HTTP/1.1
Content-Type: multipart/form-data; boundary=xxBOUNDARYxx
Content-Length: {PUT body length in bytes}

--xxBOUNDARYxx
Content-Disposition: form-data; name="Resource"; filename="TEST_SCORM.zip"
Content-Type: application/zip

{file data bytes}
--xxBOUNDARYxx--

Updating the profile image. Here’s an example showing what the actual HTTP request looks like for a user updating their own profile image:

POST https://someLMShost.edu/d2l/api/lp/{version}/profile/myProfile/image HTTP/1.1
Content-Type: multipart/form-data; boundary=xxBOUNDARYxx
Content-Length: {POST body length in bytes}

--xxBOUNDARYxx
Content-Disposition: form-data; name="profileImage"; filename="my_new_profile_image.png"
Content-Type: image/png

{image file data bytes}
--xxBOUNDARYxx--

Upload to create a new course import job. Her’s an example showing what the actual HTTP request looks like for creating a new course import job request:

POST https://someLMShost.edu/d2l/api/le/{version}/import/{org-unit-id}/imports/ HTTP/1.1
Content-Type: multipart/form-data; boundary=xxBOUNDARYxx
Content-Length: {POST body length in bytes}

--xxBOUNDARYxx
Content-Disposition: form-data; name="file"; filename="ImportPackage.zip"
Content-Type: application/zip

{import package data bytes}
--xxBOUNDARYxx--

Upload to ePortfolio. Here are two examples showing what uploads to ePortfolio look like.

This shows a simple artifact file upload:

POST https://someLMShost.edu/d2l/api/eP/{version}/artifacts/file/upload HTTP/1.1
Content-Type: multipart/form-data; boundary=xxBOUNDARYxx
Content-Length: {POST body length in bytes}

--xxBOUNDARYxx
Content-Type: text/plain
Content-Disposition: form-data; name="name"

UploadFileName.txt
--xxBOUNDARYxx
Content-Type: text/plain
Content-Disposition: form-data; name="description"

Description for the uploaded file.
--xxBOUNDARYxx
Content-Type: text/plain
Content-Disposition: form-data; name="file"; filename="UploadFileName.txt"

{file data bytes}
--xxBOUNDARYxx--

This shows an eP package import to multiple users:

POST https://someLMShost.edu/d2l/api/eP/{version}/import/new HTTP/1.1
Content-Type: multipart/form-data; boundary=xxBOUNDARYxx
Content-Length: {POST body length in bytes}

--xxBOUNDARYxx
Content-Type: text/plain
Content-Disposition: form-data; name="targetUsers"

12345
--xxBOUNDARYxx
Content-Type: text/plain
Content-Disposition: form-data; name="targetUsers"

67890
--xxBOUNDARYxx
Content-Type: applicaiton/zip
Content-Disposition: form-data; name="file"; filename="import-package.zip"

{file data bytes}
--xxBOUNDARYxx

Some items of note:

• You must provide a top-level Content-Length header that declares the length of the entire request body in bytes.

• The Content-Disposition header for the part you’re uploading will have a name field whose value varies from API call to API call; in the LR case above, it must be “Resource”; in the case of uploading an attachment for a news item, it should be “file”. Providing the wrong value here can mean that the back-end service will not be able to properly hand off the uploaded data the service tool using it.

RFC2388 Multipart/mixed

Medium-sized simple file uploading (for example, dropbox submissions, or creating news events or discussion posts with attachments) gets done using a multipart/mixed method similar to that described in RFC 2388. These actions typically use a JSON structure as the first part, to provide the meta-data for the file to upload, followed by a part containing the file’s actual data.

Upload to course content. Here’s an example showing what the actual HTTP request looks like for a file topic upload to course content:

POST https://someLMShost.edu/d2l/api/le/{version}/{orgUnit}/content/modules/{moduleId}/structure/ HTTP/1.1
Content-Type: multipart/mixed;boundary=xxBOUNDARYxx
Content-Length: {POST body in length in bytes}

--xxBOUNDARYxx
Content-Type: application/json

{ "TopicType": 1,
  "Url": "/content/enforced/170315-EXT-101/test_html_file.html",
  "StartDate": null,
  "EndDate": null,
  "DueDate": null,
  "IsHidden": false,
  "IsLocked": false,
  "Title": "TestTitle",
  "ShortTitle": "Test",
  "Type": 1,
  "Description": {"Content": "This is a test file", "Type": "Text"},
  "MajorUpdate": null,
  "MajorUpdateText": null,
  "ResetCompletionTracking": null }

--xxBOUNDARYxx
Content-Disposition: form-data; name=""; filename="file.txt"
Content-Type: text/plain

This is a sample text file
with some text content.
--xxBOUNDARYxx--

Upload to dropbox. Here’s an example showing what the actual HTTP request looks like for a simple upload to a dropbox folder:

POST https://someLMShost.edu/d2l/api/le/{version}/{orgUnit}/dropbox/folders/{folderId}/submissions/mysubmissions HTTP/1.1
Content-Type: multipart/mixed; boundary=xxBOUNDARYxx
Content-Length: {POST body length in bytes}

--xxBOUNDARYxx
Content-Type: application/json

{ "Text": "Here you go", "Html": null }
--xxBOUNDARYxx
Content-Disposition: form-data; name=""; filename="testFile.jpg"
Content-Type: image/jpeg

{binary JPEG data from file}
--xxBOUNDARYxx--

Upload to news. Here’s an example showing what the actual HTTP request looks like for a news event with two attachments (a discussion with attachments uses a similar structure):

POST https://someLMShost.edu/d2l/api/le/{version}/{orgUnit}/news/ HTTP/1.1
Content-Type: multipart/mixed;boundary=xxBOUNDARYxx
Content-Length: {POST body length in bytes}

--xxBOUNDARYxx
Content-Type: application/json

{ "EndDate": null,
  "IsPublished": true,
  "ShowOnlyInCourseOfferings": false,
  "Title": "Test title",
  "Body": { "Text": "Test body text", "Html": null },
  "StartDate": "2013-02-20T13:15:30.067Z",
  "IsGlobal": false }

--xxBOUNDARYxx
Content-Disposition: form-data; name="file 0"; filename="file.txt"
Content-Type: text/plain

This is a sample text file
with some text content.

--xxBOUNDARYxx
Content-Disposition: form-data; name="file 1"; filename="img-225x225.png"
Content-Type: image/png

{image data here}
--xxBOUNDARYxx--

Notes.

• You must provide a top-level Content-Length header that declares the length of the entire request body in bytes.

• The first part of the multipart upload request must be the JSON block.

• The JSON block’s precise contents might vary from request to request: please double-check that you’re using the right structure, depending upon the upload route you’re using.

  The previous example shows RichText JSON block used by the dropbox folder submissions route.

  If you’re uploading a content file topic to a course offering’s content store, then you should instead use a Content.ContentObjectData JSON block.

• The Content-Disposition header for the file data you’re uploading should include an empty name field, and a filename field with the file name for the file you’re uploading on the local file system.

Resumable uploads¶

The protocol for a resumable upload comprises three overall steps, summarized here and more fully explained further on in this section:

• The client must initiate a new upload via an “upload” action to acquire a unique upload key from the service.

• The client then uses this upload key to upload the binary data to a temporary location on the service.

• Finally, the client must use a “save” action, providing the upload key, to direct the service to attach the temporary file data to an LMS object in the service.

Note that the precise actions used for resumable uploads may vary from API domain to domain, but the general steps will be the same, illustrated in the following diagram.

        sequenceDiagram
   autonumber
   participant Client
   participant Service

   note over Client,Service: Acquire upload key
   Client->>Service: {new upload action}<br/>X-Upload-Content-Type: {mime-type}<br/>X-Upload-Content-Length: {total-zie}<br/>X-Upload-File-Name: {file-name}

   Service-->>Client: 308 Resume Incomplete<br/>Location: /d2l/upload/{key}

   note over Client,Service: Upload file data
   Client->>Service: POST https://{service.domain}/d2l/upload/{key}<br/>Content-Type: {mime-type}<br/>Content-Range: bytes {byte-range-A}/{total-size}

   Service-->>Client: 308 Resume Incomplete<br/>Location: /d2l/upload/{key}<br/>Range: {byte-range-A}

   Client->>Service: POST https://{service.domain}/d2l/upload/{key}<br/>Content-Type: {mime-type}<br/>Content-Range: bytes {byte-range-B}/{total-size}

   Service-->>Client: 200 OK

   note over Client,Service: Attach upload to the LMS
   Client->>Service: POST {attach file action}<br/>UploadKey={key}
   Service-->>Client: 200 OK