API Documentation

The goal is to provide a RESTful API utilizing HTTP methods as much as possible for basic operations. This page will be updated as the API becomes further defined.

Create

HTTP POST /api/create/content?multi={true | false}&inline={true | false}

Creates a learning content object and stores it in the LCR. NOTE: multi and inline are not yet supported.

Request Body: (content-type: application/json)

{
   "title": "<string>", // required
   "description" : "<string>",  //optional,
   "tags" : ["<string1>", "<string2>", ...] // optional
}

Returns on success: (content-type: application/json)

HTTP Status Code 200 OK

{
   "id" : "<string>", // the unique identifier for the new object
}

Returns on failure: (content-type: application/json)

HTTP Status Code 400

{
   "error" : "<string>", // the error message
}

HTTP POST /api/create/resource/{id}?type={file | locator}&name={resource_name}

Adds a new file and associates it to an existing Learning Object.

Parameters:

• id (required) - the unique identifier for the learning content object the file is to be associated with.
• type (file | url, default file) - the type of resource you are trying to create.
• name - the desired name for the resource. Defaults to attached filename if type is file and the full URL if the type is url
• multi (true | false, default false) - whether the body contains more than one piece of content. Currently, batch resource creation will only support all files or all urls; in other words, you cannot use multi with a mix of urls and files.

Request Body:

For type file: the raw file data.

For type url :

{
   "url" : "<string>" // a valid URL
}

Returns:

{
   "success" : boolean, // Indicates whether the request was completed successfully
   "id" : "<string>", // the unique identifier for the new resource, present only on success
   "error" : "<string>", // the error message, present only if something goes wrong
}

Additional Notes:

Though the design of this interface may seem odd at first, it actually provides a couple of advantages. First, by providing the metadata as part of the query string, we are able to both create the resource and provide basic metadata in a single request without requiring bodies containing multiple MIME types. Second, since we are wrapping the body of non-file requests (urls only for now) in json, it leaves us the ability to add additional metadata fields for new or existing types in the future.

---

Retrieve

HTTP GET /api/content/{id}

Fetches the metadata associated with a learning content object.

Parameters:

• id - the unique identifier for the learning content object the file is to be associated with.

Returns on success: (content-type: application/json)

HTTP Status Code 200 OK

{
   "title": "<string>", // the title of the learning object
   "description" : "<string>",  // a short description (140 chars max) of the learning content,
   "tags" : ["<string1>", "<string2>", ...], // tags describing the object
   "resources" : ["<string1>", "<string2>", ...], // an array of resource IDs associated with this object
}

Returns on failure: (content-type: application/json)

HTTP Status Code 400 or 404 depending on failure

{
   "error" : "<string>", // the error message
}

HTTP GET /api/resource/{id}?metadata={true | false}

Fetches a resource or its associated metadata.

Parameters:

• metadata ( true | false, default false) - specifies whether the metadata is to be returned instead of the actual content

Returns:

Default behavior (metadata omitted or false) is to return the resource itself, according to the following rules:

• If the resource is a url, then a redirect will be performed to fetch the content of the requested resource (similar to how Google handles a clickthrough on a search results page). It is yet to be determined if the server will act as a proxy to the resource or whether it will issue some 300-like status code to redirect the request, depending on the compatibility of expected consumer technologies.
• If the resource is a file, then return the file raw file data as stored in the repository.

If metadata is set to true, then any available metadata associated with the resource will be returned as JSON. Currently, all resources have the following attributes:

{
   "id" : "<string>", // The unique identifier for this metadata object
   "name" : "<string>", // The title of the resource. Defaults to filename for files and pagename for urls if unspecified.
   "type" : "{url | file}", // The type of the resource data. Used to check for additional attributes
}

Additionally, the following parameters are provided for resources of type url:

{
   "url" : "<url>" // The original url specified by the user
}

---

Update

HTTP POST /api/update/content/{id}

Updates an existing learning content object.

Request Body: refer to /api/create/content for specification.

Returns on success:

HTTP Status Code 200 OK

Returns on failure: (content-type: application/json)

HTTP Status Code 400 or 404 depending on failure

{
   "error" : "<string>", // the error message
}

HTTP POST /update/resource/{id}?type={file | url}&name={resource_name}

Updates an existing resource or its associated metadata.

Parameters:

• id (required) - the unique identifier for the resource (NOT parent learning object) you are trying to update.
• name - the new desired name for the resource. Defaults to attached filename if type is file and the full URL if the type is url

Request Body:

For type file: the raw file data.

For type url :

{
   "url" : "<string>" // a valid URL
}

Returns:

{
   "success" : boolean, // Indicates whether the request was completed successfully
   "error" : "<string>", // the error message, present only if something goes wrong
}

---

Delete

HTTP POST /api/delete/content/{id}

Deletes a learning content object and all associated files. In the future, resources may not necessarily be associated with a single content object; thus the implications (i.e. cascading behavior) are subject to change.

Parameters:

• id (required) - The id of the content object that is to be deleted

Returns on success:

HTTP Status Code 200 OK

Returns on failure: (content-type: application/json)

HTTP Status Code 400 or 404 depending on failure

{
   "error" : "<string>", // the error message
}

HTTP POST /delete/resource/{id}

Deletes a resource and disassociates it with its parent learning content object.

Parameters:

• id (required) - The id of the resource that is to be deleted

Returns:

{
   "success" : boolean, // Indicates whether the request was completed successfully
   "error" : "<string>", // the error message, present only if something goes wrong
}