Metadata Structure for JSON¶

In order to allow JSON responses to contain both a data payload and a bit of metadata about that payload, we use the following structure for all JSON generated from our API:

{
  "meta": { ... }
  "data": { ... }
}

The “meta” property contains all metadata, for example related to caching, paging, performance indicators, or auxiliary/warning messages from the server. For example, here is a sample JSON response for a user’s details that includes pagination details in meta:

{
  "meta": {
     "paging": {
        "totalItems": 59642,
        "pageNumber": 1,
        "startIndex": 0,
        "limit": 125
     },
     "type": "list<item>"
   },
   "data":
        "articles": [
            {
                "title": "Parse.ly releases its Publisher Platform and API",
                "score": 10.0,
                "signature_hash": "cbe668d4b7e2545cf4890ce1cf9bb47b",
                "updated": "2010-01-24 19:01:57",
                "unique_id": "LNqp" //, ...
            } //, ...
        ]
}

This way, direct properties from this payload could be accessed like this:

var response = getItemsResponse();
var articles = response.data.articles;
var meta = response.meta;

assert meta.type == "list<item>";

for (var i = 0; i < articles.length; i++) {
    var article = articles[i];
    // do something with article
}

Paging Metadata¶

The purpose of paging metadata is to make it possible to return paginated results. Think of a Google search results screen. What important information do you need for pagination to work properly, with minimal coding on the client-side?

Using the “item query” example from above, we had a list<item> we could page through. The current page is specified as paging.pageNumber. A frontend might use the information as follows:

var response = getItemsResponse()
var meta = response.meta;
var articles = response.data.articles;
assert meta.type == "list<item>";

var resultsTemplate = Ext.XTemplate(
      "<div id='resultsNavigator'>"
       "Pg {pageNumber}: ",
       "Showing {limit} articles out of ",
       "{totalItems} articles total"
      "</div>")

resultsTemplate.overwrite(meta.paging, Ext.get("results"));

Date Representation¶

We need to ensure that all dates that are represented on the wire meet the following criteria:

• Serialized into UTC timezone, rather than server local time.
• Deserialized from UTC and then timezone-adjusted based on user preferences.
• Represent up to millisecond precision.
• Can easily be parsed and processed into datetime objects on the Python side, into Date objects on the Javascript side, and with other DateTime abstractions on other platforms.

To this end, we output all our dates using the ISO8601 date format, with no time zone information included. We don’t include time zone information because all of our datetimes are assumed to be in Coordinated Universal Time (UTC).