Response Format

The eMusic API is capable of returning data in three different formats: XML, JSON and JSONP (JSON with Padding). XML is a platform-neutral document format. JSON and JSONP are designed to be easily consumable by JavaScript. The desired response format is specified by the developer with each request.

RESPONSE PAYLOAD

The contents of the XML and JSON / JSONP are largely identical (one-to-one correlation) with only a few notable exceptions. The first exception is the response payload.

The XML response contains both the XML document header and the XML document root element named "response". The JSON response does not contain either of these components.

ARRAYS / LISTS

In order to make the concept of arrays work for both XML and JSON, we have introduced the concept of a "list" element in XML. All XML elements that represent an array contain the attribute "list" with a value of "true". They also contain the "size" attribute which is set, not surprisingly, to the number of elements in the list. This list element is largely implicit in the JSON response. (See examples below.)

Why do we do this? Developers using XML can quickly identify arrays in structured content. And developers using JSON can conveniently reference arrays as expected. That is, instead of having to type "activeDecades.decade[0]" or "activeDecades.decade.length" -- creating double references for all arrays -- a JSON developer can use"activeDecades[0]" or "activeDecades.length".

SIMPLE TYPES

XML types (integers, strings, boolean, etc.) for attribute / element values are specified in the various schemas, and implied somewhat in the attribute / element names. JSON variables are mapped to the appropriate JavaScript type. That is, integers are integers, strings are strings, etc.

EXAMPLES

Here is the same method response using each of the three formats. First, XML:

<?xml version="1.0" encoding="UTF-8"?>
<response xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <status code="200">ok</status>
    <options format="xml"/>
    <artist group="false" id="10559083" name="Bob Marley" published="true" url="http://www.emusic.com/artist/Bob-Marley-MP3-Download/10559083.html">
    <origin location="St. Ann, Jamaica"/>
    <death location="Miami, FL"/>
    <activeDecades list="true" size="3">
        <decade>1960</decade>
        <decade>1970</decade>
        <decade>1980</decade>
    </activeDecades>
    </artist>
</response>

Now, in JSON:

{
    "status": {
        "code": 200,
        "name": "ok"
    }
    "options": {"format": "json"},
    "artist": {
        "id": 10559083,
        "name": "Bob Marley",
        "url": "http://www.emusic.com/artist/Bob-Marley-MP3-Download/10559083.html"
        "published": true,
        "group": false,
        "origin": {"location": "St. Ann, Jamaica"},
        "death": {"location": "Miami, FL"},
        "activeDecades": [
            1960,
            1970,
            1980
        ],
    },
}

Now, in JSONP:

someMethod({
    "status": {
        "code": 200,
        "name": "ok"
    }
    "options": {"format": "json"},
    "artist": {
        ...(same as JSON)...
    },
});

Note that the JSONP response wraps the JSON response with the specified JavaScript method name. For more on JSON and JSONP, consider the Wikipedia Entry.

version 7 as of 2 years ago by eMusic Admin

0 Comments

Please sign in to post a comment.