Output Format

This section describes various formats in which the API response is received using queries inside the resource file. The response type (JSON/XML) can be determined using the Accept as described here.


Each of the <Query>, <Update> or <Execute> tags, produces its own output and since all these tags can be used inside a single <Request> tag their output is clubbed together and sent as a JSON array containing different JSON objects. So typical response to our API call will have output format as follows

[ 
    { 
        "jsonObject": "value1"
    },
    { 
        "jsonObject": "value2"
    },
    { 
        "jsonObject": "value3"
    }
]

Single query response

Consider a follow resource file

<?xml version="1.0" encoding="UTF-8" ?>
<Resource xmlns="http://xml.metamug.net/resource/1.0" v="1.0">
    <Request method="GET">
        <Query>
            SELECT name, rating FROM movie
        </Query>
    </Request>
<Resource>

Gives output in this format

[ 
    { 
        "name": "Captain America",
        "rating": 2.5
    },
    { 
        "name": "Passengers",
        "rating": 5
    },
    { 
        "name": "Revolver",
        "rating": 2.5
    },
    { 
        "name": "The Godfather",
        "rating": 3.4
    }
]

Here you can see data of each row is being represented as single JSONObject and all such JSONObjects are clubbed inside a JSONArray.

Multiple query response

Now consider this resource file which produces more than one response.

<?xml version="1.0" encoding="UTF-8" ?>
<Resource xmlns="http://xml.metamug.net/resource/1.0" v="1.0">
    <Request method="GET">
        <Query>
            SELECT name, rating FROM movie
        </Query>
        <Query>
            SELECT user_id, user_name FROM user
        </Query>
    </Request>
<Resource>

Gives output

[
    [   
        {
            "name": "Captain America",
            "rating": 2.5
        },
        {
            "name": "Passengers",
            "rating": 5
        },
        {
            "name": "Revolver",
            "rating": 2.5
        },
        {
            "name": "The Godfather",
            "rating": 3.4
        }   
    ],
    [
        {
            "user_id": 1,
            "user_name": "Foo"
        } 
    ]
]

Since we’ve two queries data from each query is enclosed within a JSONArray and both the JSONArrays is enclosed inside the main Array. The response output is in the same order as that of the <Query> tag order in the resource file.

Verbose

The Update query generally returns how many records have been updated or DDL queries returns a generic message which we need not show as a response to the developer for all such queries the response output can be suppressed by using a verbose attribute in <Query>, <Update> or <Execute> tag.

Consider the following resource file

<?xml version="1.0" encoding="UTF-8" ?>
<Resource xmlns="http://xml.metamug.net/resource/1.0" v="1.0">
    <Request method="GET">
        <Query verbose="false">
            SELECT name, rating FROM movie
        </Query>
        <Query>
            SELECT user_id, user_name FROM user
        </Query>
    </Request>
<Resource>

Here we’ve suppressed the output of 1st <Query> tag due to which it is considered as a resource file with single <Query> tag as per Figure 1. The above resource file give generates the following output

[
    {
        "user_id": 1,
        "user_name": "Foo"
    } 
]

Persist

Quite often we want to use a value returned by one query into another query, sure Sub-Query is an option for them but if we want to keep it simple and easy to understand developers can make of Persist attribute to store a single record-set for that particular request.

Consider the following resource file.

<?xml version="1.0" encoding="UTF-8" ?>
<Resource xmlns="http://xml.metamug.net/resource/1.0" v="1.0">
    <Request method="GET">
        <Query verbose="false" persist="true">
            SELECT user_name as "name" rating FROM user
        </Query>
        <Query>
            SELECT $name as 'User Name'
        </Query>
    </Request>
<Resource>

Here I’ve suppressed the output of 1st query, persisted its result i.e. is the user_name column’s value and used it in the next query. The persisted value(s) can be accessed using the column’s alias name (if present) or directly by the column name from that table. If the column is declared using an alias then you’ll have to use the alias for accessing the persisted value. Let’s see the output of the above resource file

[
    {
        "user_name": "Foo"
    } 
]

As you can see the name from user table is persisted and used in a subsequent query.

Error Output

Errors are an integral part of any code development they help us identify our flaws and shortcomings, so even though errors seem to be a bad guy it is necessary that they are presented succinctly so that developers can identify the root cause of the error. So whenever there is an error we give a simple error response in the following format.

{
    "errorID": 3802718736064892400,
    "message": "API Error. Please contact your API administrator.",
    "status": 512
}

So instead of giving a dirty error message in API response, we give the developer an errorId which he can use to see the detailed error trace from the console but sometimes errors are necessary and we want things to fail for certain condition. For which we’ve two attributes onerror and onblank. onblank is used in conjunction with persist attribute whereas onerror can be used anytime. With these attributes one can give a custom error message when an error occurs, this is typically used if the data breaks any unique-key constraint or foreign-key constraints.

Consider the following resource file.

<?xml version="1.0" encoding="UTF-8" ?>
<Resource xmlns="http://xml.metamug.net/resource/1.0" v="1.0">
    <Request method="GET">
    <!-- I've purpose written Incorrect query to show you the use of onerror attribute -->
        <Query onerror="Incorrect query">
            SELECT name,rating movie
        </Query>
    </Request>
<Resource>

The given <Query> will generate following output

{
    "errorID": 7298420097052428000,
    "error": "Incorrect query",
    "message": "API Error. Please contact your API administrator.",
    "status": 512
}

Dot Notation

If you want a nested json in your json data, the dot notation helps you to do this.

<?xml version="1.0" encoding="UTF-8" ?>
<Resource xmlns="http://xml.metamug.net/resource/1.0" v="1.0">
    <Request method="GET">
        <Query>
            SELECT `name`,`rating`, releaseDate as 'info.releaseDate' from movie 
        </Query>
    </Request>
<Resource>

The dot notation in the resource file changes to nested json in the output.

{  
    "name":"Passengers",
    "rating":5,
    "info": {  
        "releaseDate":null
    }
}

If we change our query to

SELECT `name`,`rating` as 'info.rating', releaseDate as 'info.releaseDate' from movie 

rating and releaseDate both will appear under the same attribute info.

{  
    "name":"Passengers",
    "info": {  
        "rating":5,
        "releaseDate":null
    }
}