Platform API Documentation

The Icodeon Platform exposes a RESTful web services API. HTTP requests are constructed using a URL language templates and respresentations are returned in the HTTP response.

Full API Documentation is here.

Also see documentation from the UK Open University Open Learn website.

The URL Language uses:

  • plural noun keywords

  • path variables

  • extension path variables

  • selector variables

  • punctuation characters

  • query parameters

  • HTTP verbs

to specify a format of a representation of a resource. See the example:
GET http://api.icodeon.com/cartridges/ccvtd0001v1p13/items/@first.gif?width=300

This is a request to return a thumbnail image of the first item from packaged educational content. The package identifier ("ccvtd0001v1p13") is encoded as a path variable after a keyword ("cartridges").

A selector ("@first") is applied to address the first item in the package and the required format is specified as the extension path variable ("gif").

Finally a URL query parameter is used (width=300) to control the width of the returned thumbnail image.

For more examples of using the URL Language with the Icodeon Platform, see the CC Plaform Blog.

The URL Language with the Icodeon Platform is strongly influenced by the OpenSocial RESTful Protocol Specification, as well as the RESTful Web Services text by Leonard Richardson and Sam Ruby.


URL Language Overview

  • Path key words and path variables are used for encoding variable values. Key words are always plural nouns:
    /keyword1/{value}/keyword2

  • Path separator characters are used for encoding hierarchy:
    /parent/child

  • Comma punctuation characters are used for ordered lists:
    /parent/child/item1,item2

  • Semi-colon punctuation characters are used for unordered lists:
    /parent/child/param;item

  • Selectors are reserved for defined meanings:
    /parent/@selector

  • POST requests are made to parent URIs to create a new resource. The representation sent with along with a POST request describes the initial state of the new resource. The Platform generates the new child identifier value:
    POST /parent would return: {identifier}

  • PUT requests are made to child URIs to create or change a resource. The representation sent with along with a PUT request describes the initial state of the new resource or a new state for an existing resource. If the PUT request is creating a new resource then the requesting client generates the new child identifier value:
    PUT /parent/{identifier}

  • DELETE requests are made to child URIs. The requesting client specifies an exisiting child identifier value:
    DELETE /parent/{identifier}

  • GET requests are made to both parent and child URIs. The requesting client may specify an exisiting child identifier value:
    GET /parent would return a representation about a collection of resources, whilst
    GET /parent/{identifier} returns the representation of a particular resource.

  • Representation format is specified either as a file extension, or as a URL parameter, or as a HTTP header:
    /parent/{identifier}.{ext} or /parent/{identifier}?format={format} If this information is missing, then the Platform will attempt to read the requested representation from the HTTP request headers, or return the default respresentation.

  • Input variable values for algorithms are specified as URL query parameter or representation key/value pairs:
    /parent/child?width={n}


Keywords and APIs

Keywords are plural nouns. A path separator character followed by path variable identifies the instance of the entity.

  • /cartridges/{cartridge_id} Typically used in a GET request to return a representation of a package for displaying the title of a content and it's meta data. (Documentation Page).

  • /cartridges/{cartridge_id}/items/{item_id} Always used in a GET request to return a representation of the resource associated package manifest item element. Typically used to build menu and navigation devices. Representations can be for leaf node and non-leaf node items.(Documentation Page).

  • /cartridges/{cartridge_id}/items/{item_id}/images/{image_id} Always used in a GET request to return a representation of a image from an HTML file referenced by resource associated package manifest item element. Typically used to build grapical menus and links.

  • /cartridges/{cartridge_id}/items/{item_id}/files/{file_id} Always used in a GET request to return a representation of a file related to a resource associated package manifest item element. (Documentation Page).

  • /cartridges/{cartridge_id}/items/{item_id}/topics/{topic_id} Typically used in a GET request to return a representation of a discussion topic. (Documentation Page).

  • /cartridges/{cartridge_id}/items/{item_id}/topics/{topic_id}/activities/{activity_id} Typically used in a GET or POST request to return or submit a representation of a discussion topic comment. An activity is similar to a post or message to an activity stream or wall on a social network.

  • /cartridges/{cartridge_id}/items/{item_id}/assessments/{assessment_id} Typically ussd in a GET request to return a representation of an assessment.

  • /cartridges/{cartridge_id}/items/{item_id}/assessments/{assessment_id}/questions/{question} Typically ussd in a GET or PUT request to return or submit a representation of a assessment question. (Documentation Page).

  • /cartridges/{cartridge_id}/items/{item_id}/apps/{app_id} Typically ussd in a GET request to return a representation of a cartridge Basic LTI Launch link. (Documentation Page).

  • /pings/@now Typically used in a GET request to return a respresentation of a timestamp as simple test utility.


Formats

  • .json (default) Media Type: Java Script Object Notation (application/json). JSON representation according to the OpenSocial RESTful Protocol Specification description.

  • .xml Media Type: Extensible Markup Language (application/xml). XML representation according to the OpenSocial RESTful Protocol Specification description.

  • .txt Media Type: Plain Test (text/plain). The Platform will attempt to read the resource document and return a text representation. For example, HTML documents are read tags are stripped out, and the textual content is returned. Useful for building taster absracts.

  • .js Media Type: Javascript (application/javascript). JavaScript representations used for rendering widgets.

  • .gif Media Type: Graphics Interchange Format (image/gif). Used for thumbnail image representations.

  • .jpg Media Type: Joint Photographic Experts Group (image/jpg). Used for thumbnail image representations.

  • .png Media Type: Portable Network Graphics (image/png). Used for thumbnail image representations.

In addition to these standard formats, the Platform also introduces some (Icodeon) vendor specific formats that are requested using characters in the extension path variable.

  • .app Used to launch an web application that displays the resource, such as the Icodeon Cartridge Explorer.

  • .do Used to redirect to a landing page related to the resource. The platform can use a plug-in layer to determine the landing page based on a set of properties about the resource.

  • .go Used to redirect to the Common Cartridge resource itself, rather than a containing web application or landing page.

NOTE: Not all response formats are supported for every resource. There is no default PNG image representation of a discussion topic, for example. So some requests will return "Not Implemented": either because those representation formats are actually not yet implemented (but will be in the future), or because no implemenation is possible.


Selectors

  • @size Returns the number of elememts in a collection, such as the number of files described by a resource related to an item element in a package manifest, the number of questions in an assessment, the number of comments in a discussion.

  • @first Selects the repesentation of the first element in a collection, such as the first item element in a package manifest or the first question in an assessment.

  • @last Selects the repesentation of the last item in a collection.

  • @default Resources such as discussion topics, assessments and Basic LTI links will are instantiated as a particular instance. This selector addresses a default instance.

  • @now


URL Query Parameters

  • method={VERB} Specifies that the specified HTTP verb is to be used. For example a GET request can be sent using method=DELETE to delete a resource.

  • format={media type} Specifies the representation format. Supported values: html, xhtml, xml, json, atom, js, gif, png, jpg. Except for specialised representations, such as images, the default is json if not specified.

  • start={n} Specifies the start index in a paged collection, assuming a zero based index. Supported values: any integer greater than or equal to zero. If not specified the default is 0.

  • limit={n} Specifies the size of a paged collection. Supported values: any integer greater than zero. If not specified the default is 10.

  • api_key={consumer key} Used to validate requests from a particular website domain where the identity of the user is not required, but the identity of the domain is.

  • oauth_consumer_key={consumer key} Used to validate requests from a particular website domain where the identity of the user is authenticated.