Developer Platform (December 2024)

ePortfolio Artifacts

«  ePortfolio Objects   ·  [   home  ·   reference  ·   community   |   search  ·   index   ·  routing table   ·  scopes table   ]   ·  ePortfolio Reflection  »

Artifacts in the ePortfolio service can be files or links to web resources. As files can be large, the service expects to handle the creation of file artifacts in a staged manner:

  1. Start a file upload request to pass the file’s data up to the server where it can be put in temporary storage. As part of this process, the server provides you with an upload key.

  2. Then, provide the properties for a new file artifact, including the upload key to indicate the server which uploaded file’s data it should attach to the file artifact.

Attributes

Artifacts come in a variety of forms all based on the base EP.EpObject structure: the generic EP.Artifact, and a number of more specific derived types.

Warning

As with the base EP object structure, you should never seek to modify the ObjectId property of an Artifact EP objects once the service has established it; rather, if you use an action to update an Artifact, you should just reflect back the ObjectId value provided to you by the service for the object in the first place.

However, when you’re first creating an artifact, you should ensure to set the ObjectId property to zero ("ObjectId":0) to indicate to the service that you want it to create a new artifact and allocate a new ID.

EP.Artifact

A basic Artifact EP object’s structure does not differ from the general form of the EpObject, except it has an appropriate EPOBJ_T value for the ObjectTypeId property ("<number:EPOBJ_T:Artifact>").

EP.FileArtifact

A FileArtifact EP object’s structure differs in two ways from the general form of the EpObject data block:

  • Its ObjectTypeId property will be set to the appropriate EPOBJ_T value ("<number:EPOBJ_T:FileArtifact>").

  • Four additional properties appear in both the Create and Fetch forms of the EP object’s data block:

    {
    "FileSize": <number>,
    "FileName": <string>,
    "Extension": <string>,
    "UploadKey": <string>
}
EP.FormArtifact

A FormArtifact EP object’s structure does not differ from the general form of the EpObject, except it has an appropriate EPOBJ_T value for the ObjectTypeId property ("<number:EPOBJ_T:FormArtifact>").

EP.LEArtifact

An LEArtifact EP object’s structure does not differ from the general form of the EpObject, except it has an appropriate EPOBJ_T value for the ObjectTypeId property ("<number:EPOBJ_T:LEArtifact>").

EP.UrlArtifact

An UrlArtifact EP object’s structure differs in two ways from the general form of the EpObject:

  • Its ObjectTypeProperty will be set to the appropriate EPOBJ_T value ("<number:EPOBJ_T:UrlArtifact>").

  • A single additional property appears in both the Create and Fetch forms of the EP object’s data block: "Url": "<string>".

Actions

DELETE /d2l/api/eP/(version)/artifact/(objectId)

Delete a particular EP artifact.

Parameters:
Status Codes:
API Versions:

  • 2.5+ – Route first appears in LMS v10.4.0.

  • 2.4- – Obsolete as of LMS v10.7.0.

DELETE /d2l/api/eP/(version)/artifact/file/(objectId)

Delete a particular EP file artifact.

Parameters:
Status Codes:
API Versions:

  • 2.5+ – Route first appears in LMS v10.4.0.

  • 2.4- – Obsolete as of LMS v10.7.0.

DELETE /d2l/api/eP/(version)/artifact/link/(objectId)

Delete a particular EP link artifact.

Parameters:
Status Codes:
API Versions:

  • 2.5+ – Route first appears in LMS v10.4.0.

  • 2.4- – Obsolete as of LMS v10.7.0.

GET /d2l/api/eP/(version)/artifact/(objectId)

Retrieve a particular EP artifact.

Parameters:
Query Parameters:

  • c – Optional boolean value. If “true”, include comments attached to artifact.

Status Codes:
API Versions:

  • 2.5+ – Route first appears in LMS v10.4.0.

  • 2.4- – Obsolete as of LMS v10.7.0.

Return. This action retrieves an Artifact JSON data block.

GET /d2l/api/eP/(version)/artifact/file/(objectId)

Retrieve a particular EP file artifact.

Parameters:
Query Parameters:

  • c (boolean) – Optional. If “true”, include comments attached to the file artifact.

Status Codes:
API Versions:

  • 2.5+ – Route first appears in LMS v10.4.0.

  • 2.4- – Obsolete as of LMS v10.7.0.

Return. This action retrieves a FileArtifact JSON data block.

GET /d2l/api/eP/(version)/artifact/link/(objectId)

Retrieve a particular EP link artifact.

Parameters:
Query Parameters:

  • c (boolean) – Optional. If “true”, include comments attached to the file artifact.

Status Codes:
API Versions:

  • 2.5+ – Route first appears in LMS v10.4.0.

  • 2.4- – Obsolete as of LMS v10.7.0.

Return. This action retrieves a UrlArtifact JSON data block.

POST /d2l/api/eP/(version)/artifacts/file/new

Create a new file artifact by starting a new resumable upload or attaching an already uploaded file.

Parameters:
JSON Parameters:

  • FileArtifact (EP.FileArtifact) – File artifact property data for your upload.

Status Codes:
API Versions:

  • 2.5+ – Route first appears in LMS v10.4.0.

  • 2.4- – Obsolete as of LMS v10.7.0.

Input. If you want to initiate a resumable upload process, your POST request must include three special headers:

  • X-Upload-Content-Type to indicate the file’s mime type.

  • X-Upload-Content-Length to indicate the file’s total size, in bytes.

  • X-Upload-File-Name to indicate the file name for the file.

If you’ve already completed a file upload, as part of the resumable upload process, the service will have provided you with an upload key value. In your FileArtifact JSON block, set the UploadKey property to this value so that the service can find the file data to attach to your new file artifact (and do not include the three special headers to your request).

Return. If you successfully initiate a resumable upload process, the service will respond with an HTTP 308, and provides you with an upload key value that you can use to attach the uploaded file data to a file artifact EP object.

If you’re attempting to attach an already uploaded file, this action returns a FileArtifact JSON data block for the new file artifact created.

POST /d2l/api/eP/(version)/artifacts/file/upload

Create a new file artifact from a simple file upload.

Parameters:
Query Parameters:

  • name (string) – Optional. Name for the file artifact (if absent, default value is “file”).

  • description (string) – Optional. Description for the file artifact.

Status Codes:
API Versions:

  • 2.5+ – Route first appears in LMS v10.4.0.

  • 2.4- – Obsolete as of LMS v10.7.0.

Input. Provide a simple POST multipart/form file upload (RFC 1867) to provide the file data for the new artifact.

POST /d2l/api/eP/(version)/artifact/file/(objectId)

Update an existing file artifact.

Parameters:
JSON Parameters:

  • FileArtifact (EP.FileArtifact) – Updated file artifact property data for file artifact.

Status Codes:
API Versions:

  • 2.5+ – Route first appears in LMS v10.4.0.

  • 2.4- – Obsolete as of LMS v10.7.0.

Return. This action returns a FileArtifact JSON data block for the updated file artifact.

POST /d2l/api/eP/(version)/artifacts/link/new

Create a new link artifact.

Parameters:
JSON Parameters:

  • UrlArtifact (EP.UrlArtifact) – URL artifact property data for your new link artifact.

Status Codes:
API Versions:

  • 2.5+ – Route first appears in LMS v10.4.0.

  • 2.4- – Obsolete as of LMS v10.7.0.

Return. This action returns a UrlArtifact JSON data block for the new link artifact created.

POST /d2l/api/eP/(version)/artifact/link/(objectId)

Update an existing link artifact.

Parameters:
JSON Parameters:

  • UrlArtifact (EP.UrlArtifact) – Updated URL artifact property data for link artifact.

Status Codes:
API Versions:

  • 2.5+ – Route first appears in LMS v10.4.0.

  • 2.4- – Obsolete as of LMS v10.7.0.

Return. This action returns a UrlArtifact JSON data block for the updated link artifact.

«  ePortfolio Objects   ·  [   home  ·   reference  ·   community   |   search  ·   index   ·  routing table   ·  scopes table   ]   ·  ePortfolio Reflection  »