Skip to content

API Documentation

Jump to bottom
armontoya edited this page Mar 21, 2012 · 33 revisions

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.

Packages

HTTP POST /api/create/package?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 GET /api/package/{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" : [ 
      { 
           "name" : "<string>", 
           "type" : "<string>", 
           "<url | file_id>" : "<string>" 
      },
      ... ]
}

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

HTTP Status Code 400 or 404 depending on failure

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

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

Updates an existing learning content object.

Request Body: refer to /api/create/package 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 /api/delete/package/{id}

Deletes a learning package and all associated resources.

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
}

Resources

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

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

Parameters:

  • id (required) - the unique identifier for the learning package the file is to be associated with.
  • type (file | locator, 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 locator :

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

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

HTTP Status Code 200 OK

{
   "id" : "<string>", // the local identifier for the new resource
}

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

HTTP Status Code 400

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

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.

HTTP GET /api/package/{id}/resource/{resourceNumber}

Fetches a resource or its associated metadata.

Parameters:

  • id - The learning package unique identifier.
  • resourceNumber - the local resource identifier. Note that this is unique only to the package; it is not a globally unique identifier.

Returns:

The resource, 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-variant 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.

HTTP POST /update/package/{id}/resource/{resourceNumber}name={resource_name}

Updates an existing resource or its associated metadata.

Parameters:

  • id (required) - the unique identifier for the package whose resource is being updated.
  • resourceNumber (required) - the local identifier for the resource you would like 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 locator :

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

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/package/{id}/resource/{resourceNumber}

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

Parameters:

  • id (required) - The id of the package whose resource is to be deleted
  • resourceNumber (required) - the local identifier for the resource you want to delete 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
}

Clone this wiki locally