Pearson
Always Learning

This API retrieves a list of the documents that are in the selected category. It is also the API you'll use to add a document to a category.

Note: To upload files with the APIs, you will need to use TempFiles API first. Once a file is uploaded to TempFiles, that API provides a URL that you'll send to the this API.



Supported Roles and Authentication Protocols

Type Supported Values
Authentication Protocols OAuth 2.0
Valid for Roles (OAuth 2): Professor, Teaching Assistant, Student

API Request

API Endpoints

HTTP Verbs and URIs

GET /courses/{courseId}/docSharingCategories/{categoryId}/docSharingDocuments{.format}
  • Retrieves a list of the documents in the specified Doc Sharing category.
GET /courses/{courseId}/docSharingCategories/{categoryId}/docSharingDocuments/{docId}{.format}
  • Retrieves the detail about a single document in the category, identified by ID.
POST /courses/{courseId}/docSharingCategories/{categoryId}/docSharingDocuments{.format}
  • Create a new document in the category.

Parameters

Parameter Description Valid Values
{courseId} LearningStudio Course ID. Numeric ID issued by LearningStudio. Note this API does not support course overloads.
{categoryId} LearningStudio Doc Sharing Category ID.
  • Numeric ID issued by LearningStudio
{docId} LearningStudio Document ID.
  • Numeric ID issued by LearningStudio
{.format} Desired format of response data. See Response Formats. .json , .xml , or Blank

Query Parameters

No Query String Parameters are supported.

Request Body

For GET

None.

For POST

{
  "docSharingDocuments":[{
    "fileDescription":"{description}",
    "isSharedWithInstructorOnly":{shareFlag},
    "content":{
      "links":[{
        "href":"{tempFilesUrl}",
        "rel":"related"
      }]
    }
  }]
}

Property Descriptions

Name Description
{description} Text description of the document.
{shareFlag} Boolean that indicates whether the file should be shared with entire class or with instructors only.

  • true - file is only shared with course instructor (and user that uploaded the file).
  • false - file is shared with entire class or group (both instructors and students).
{tempFilesUrl} The URL provided in the fileLocation property TempFiles API response, where you will upload the file.

API Response

Response Header

This API returns the standard HTTP Status Codes used by the LearningStudio APIs. There are no special headers returned by the API for GET requests.

For POST requests, this API returns a Location header that contains a JSON-formatted payload. This is an exception to our standard use of the Location header. The format for this header will be:

Location: {"links":[{"href":"{pathToDocumentAPI}","rel":"self"}]}

To retrieve the ID, you will need to parse the value of the Location header, and then follow a GET on the {pathToDocumentAPI} value, which returns this APIs results.

Response Body

For POST Requests

Empty

For GET Requests

{
  "docSharingDocuments": [{
    "id": "{docId}",
    "fileName": "{filename}",
    "fileDescription": "{description}",
    "fileSize": "{fileSize}",
    "uploadedTime": "{uploadedTime}",
    "downloadCount": "{downloadCount}",
    "isSharedWithInstructorOnly":{shareFlag},
    "submitter": {
      "name": "{userFullName}",
      "links": [
      {
        "href": "{userObjectUrl}",
        "rel": "related"
      }
      ]
    }
  }]
}

Property Descriptions

Name Description
{docShareDocId} The LearningStudio ID for the document.
{filename} File name and extension of the attachment. For example, "somefile.pdf"
{description} A description of the document as entered when the document was added to Doc Sharing.
{fileSize} Size of the doc share document, in bytes.
{uploadedTime} Date and time the file was uploaded. Format is YYYY-MM-DDTHH:MM:SSZ
{downloadCount} Number of times the file has been downloaded.
{shareFlag} Boolean that indicates whether the file should be shared with entire class or with instructors only.

  • true - file is only shared with course instructor (and user that uploaded the file).
  • false - file is shared with entire class or group (both instructors and students).
{userFullName} First and last name of the user who submitted (uploaded) the file.
{userObjectUrl} Link to the user object for the user who submitted (uploaded) the file. You're advised not to parse this URL, but instead use a GET request of it to retrieve the user object. More about Response Links

Example: Get All Documents in a Category

Request

Endpoint

GET /courses/123456/docsharingcategories/7878/docsharingdocuments

Response

Body

{
  "docSharingDocuments": [{
    "id": 1367562,
    "fileName": "Test.txt",
    "fileDescription": "'This is a test document'",
    "fileSize": 578,
    "uploadedTime": "2010-11-12T19:46:19Z",
    "downloadCount": 0,
    "submitter": {
      "name": "John Doe",
      "links": [
      {
        "href": "https://api.learningstudio.com/users/6789876",
        "rel": "related"
      }
      ]
    },
 {
    "id": 1367563,
    "fileName": "Test2.doc",
    "fileDescription": "'This is another document'",
    "fileSize": 578,
    "uploadedTime": "2010-11-13T17:21:10Z",
    "downloadCount": 7,
    "submitter": {
      "name": "Jane Doe",
      "links": [
      {
        "href": "https://api.learningstudio.com/users/6789877",
        "rel": "related"
      }
      ]
    }
  }]
}

Example: Add a Document to Doc Sharing

Pre-requisite

You must use the TempFiles API to upload the document to LearningStudio. That API will provide a fileLocation property with the URL shown in the example request body below.

Request

Endpoint

POST /courses/123456/docsharingcategories/7878/docsharingdocuments

Body

{
  "docSharingDocuments":[{
    "fileDescription":"An interesting perspective on platform economics",
    "isSharedWithInstructorOnly":false,
    "content":{
      "links":[{
        "href":"https://api.learningstudio.com/tempfiles/65cdce02-9cfa-4065-af05-a60ad1eefaf0",
        "rel":"related"
      }]
    }
  }]
}

Response

HTTP Headers (Partial)

Location:  {"links":[{"href":"https://api.learningstudio.com/courses/123456/docSharingCategories/7878/docSharingDocuments/98765","rel":"self"}]}

Body

Empty.

1276 reads
Always Learning
Pearson