Friday, 10 April 2009

URL Language

~ This page describes the Icodeon Common Cartridge Platform API for integrating content into blogs, wikis, web pages and social networking sites ~

The platform uses a URL Language so that requests can be easily created for cartridge content.

For example, to create a reference to a thumbnail image of the first page in a cartridge, we create a request URL like this:

http://{host}/cartridges/{cartridge}/items/@first.gif

All that is required is to substitute in the name of the platform host server (the {host}) and the unique identifier of the cartridge (the {cartridge}) and the platform generates the thumbnail image.

The image can then be added to a web page as the source attribute value in an HTML image tag:

<img src="
http://api.common-cartridge.com/cartridges/
icodeon_spanish_cities/items/@first.gif"/>

The URL Language includes:

  • key words: these are part of the URL path, and are plural nouns, such as "cartridges" and "assessments".

  • path variables: these are part of the URL path. The value that was substituted in for the {cartridge} in our example above is a path variable.

  • selectors: these are part of the URL path. A selector ("@first") was used in our example to select the first item in a cartridge.

  • formats and extension variable: the part of the URL that is used to indicate the content type. The value of ".gif" in our example above is an extension variable. We used ".gif", but using ".jpg" or ".png" would mean that the platform would generate a different content type.

  • URL parameter key/value pairs: these are added after the path and extension variables as key/value pairs. For example, to create an image with a defined size, we could add the key/value pairs of "&_width=120&_height=90" to URL.

  • Puntuation characters: these can be included in URL. For example commas (,) are used represent a request for an ordered list.

The URL Language Documentation is being developed here.

So, to create a reference to a thumbnail image in the "jpg" format of the last page in a cartridge, we create a reference like this:

<img src="
http://www.common-cartridge.com/cartridges/
icodeon_spanish_cities/items/@last.jpg
?_width=120&_height=90"/>

When making requests to the Platform from external servers, we also need to add an API Key that the Platform generates for the external domain, so the final reference for the image is:

<img src="
http://www.common-cartridge.com/cartridges/
icodeon_spanish_cities/items/@last.jpg
?_api_key=abc123&_width=120&_height=90"/>

The URL language has many response formats (or "representations"), not just the graphical formats for screen shot thumbnails of pages within the cartridge.

The platform provides a choice of "representations" for all responses from the platform. For example, the platform can provide a choice of either .gif, .jpg or .png graphic formats for thumbnail images that are returned from requests.

For text based representations, the platfrom "representations" include XML, HTML, JSON and ATOM. These text based representations are conformant with well established designs, including:

  • Microformats: microformats are a set of simple, open data formats built upon existing and widely adopted standards. Instead of throwing away what works today, microformats intend to solve simple problems first by adapting to current behaviors and usage patterns (e.g. blogging). (Learn more).

  • OpenSocial: OpenSocial defines a common API for social applications across multiple websites. With standard JavaScript and HTML, developers can create apps that access a social network's friends and update feeds. Learn more).

By using well established designs for representations, developers can re-use existing libraries, style sheets and code to process the responses from the Icodeon Common Cartridge Platform

No comments:

Post a Comment