David Janes' Code Weblog

To quickly review, the AUAPI sees API results as composing of two parts. A “response” (formerly the “meta”) and “items”, composed of one or more items. This division is documented in Work Object Records.

Here is how we use Atom to encode API items in the AUAPI (we will document “response” in a different post). This sticks fairly closely to the Atom standard, the differences being in how each term is serialized into JSON for convenience and ease of use – and that there’s no real required elements. Don’t forget that each “item” is a discrete unit returned from an API and represents “whatever” – a Flickr photo, an Amazon product

• title (string, plain text) – the title; this is a plain text string, i.e. no entities or HTML allowed
• id (string, plain text) – a unique ID (in the context of the API being called) for this result
• content (string, HTML) – the complete text; this is HTML
• summary (string, HTML) – the summary text; this is HTML.
• link (string, URL) – this is the “main” link of whatever the item represents, a page on Amazon, a blog post’s original HTML and so forth
• links (array of dictionary) – these are other links related to the item; the format is documented below
• category (array of dictionary) – tags/categories; the format is documented below
• author (a string or dictionary) – if a dictionary, the format is documented below
• updated (string, Atom datetime format) – when the item was last updated
• posted (string, Atom datetime format) – when the item was originally posted; if using updated and/or posted, always use updated and then use posted only if you have a meaningful difference.

Links Format

links are results related to the item. The most important link should be encoded in the link item. links are a list of dictionary, each dictionary containing (further documentation):

• href (string, URI)
• rel (string, enumeration)
• type (string, MIME type)
• hreflang (string, language code)
• title (string, plain text)
• length (string, integer)

Category Format

category are the tags for the item, and are a list of a dictionary each dictionary containing (further documentation):

• @ (string, plain text) – the tag
• rel (string, from enumeration)
• scheme (string, URI)

Author Format

The author can be encoded as a string (containing the author’s name) or as a dictionary, or as a list of dictionaries. If a dictionary, this is how it should be encoded (further documentation)

• @ (string, plain text) – the author’s name
• uri (string, URI)
• email (string, email address)

Example

This is a API result from Whitepages.com, encoded as AUAPI. I have removed non-Atom items and shortened long text for clarity.

{'content': "<div class="vcard">\n<div class="fn">Jack Smith</div>...\n</div>\n",
 'id': '40b296d1a95f3b379a8108b27daf009c',
 'links': [{'href': 'http://www.whitepages.com/16176/t...',
            'rel': 'related',
            'title': 'Find Neighbours',
            'type': 'text/html'},
           {'href': 'http://www.whitepages.com/16176/track...',
            'rel': 'related',
            'title': 'Map',
            'type': 'text/html'},
           {'href': 'http://www.whitepages.com/16...',
            'rel': 'related',
            'title': 'Map',
            'type': 'text/html'},
           {'href': 'http://www.whitepages.com/16176/track/102...',
            'rel': 'alternate',
            'title': 'Whitepages.com',
            'type': 'text/html'}],
 'title': u'Jack Smith'}