Wiki

Clone wiki

cloudengine / API

CloudEngine API

Note, this document was originally written specifically for the Cloudworks API. We are currently generalizing it for CloudEngine. (PDF, last modified 15 June 2010.)

Overview

The CloudEngine application programming interface (API) (also called the Cloudworks API) allows anybody to build their own programs using CloudEngine data.

Currently the API only supports methods which do not require authentication, however, we plan to expand the API in future. We also currently only support a JSON response format, but plan to extend the API to include an XML response format in future.

Methods to retrieve data from the CloudEngine API require a HTTP GET request. The CloudEngine API uses a data over HTTP approach as opposed to a strict REST approach.

Conventions

  • The API currently uses a JSON response format and UTF-8 encoding. We plan to also provide an XML response format in future.
  • Parameter values should use UTF-8 encoding and be URL-encoded.
  • Dates in responses are in ISO 8601 format.
  • Response values like cloud.body, content.body, comment.body and author.description are JSON-encoded HTML; cloud.title, cloud.summary, author.name, author.institution and reference.text are JSON-encoded plain text; other response values contain JSON-encoded URLs, integers (as strings), objects or arrays.
  • The aim is for every object eg. cloud, user, to have an html_url and api_url. 'html_url' points to a web page representing the object, api_url points to the API, with the same format as the current request.
  • 'self_url' is a special case of an API link, in the outer-most object of a response (think <atom:link rel="self" ... /> ).
  • Images are referenced using 'thumbnail_url', which points to 32-{FILENAME} for users and 256-{FILENAME} for cloudscapes (32 pixels square and 256 pixels respectively).
  • Streams (eg. user/stream) have a 'status' item, which is a HTML formatted text with links, including attribution links.
  • For 'plural' responses, eg. user/stream, cloud/followers, search/clouds, the array is nested inside an object. The array is named 'items', that is,
    • { ... , "items": [ ... ] }
  • 'Plural' responses currently return all the items, up to an arbitrary limit of 200 - we may introduce paging for these calls in future.

API Contents

Updated