Output formats

Unless otherwise stated, the output format for objects across all models follows a consistent pattern described below.

The format is determined either with a HTTP_ACCEPT request header set to application/json or application/xml or with a GET variable, format, set to json or xml.

XML

XML responses have a root element of object or response (if the request potentially contains multiple objects). Requests for a single object (those with an endpoint containing an object id) always receive a single object representation. Requests for collections (made by querying the base endpoint) contain metadata about the request, such as pagination information.

XML representations follow this reference example:

<?xml version="1.0" encoding="utf-8"?>
<response>
  <objects type="list">
    <object>
      <field_name>field value</field_name>
      <field_name2 type="boolean">True</field_name2>
    </object>
    <object>
      <field_name type="null" />
      <field_name2 type="boolean">False</field_name2>
    </object>
  </objects>
  <meta type="hash">
      <next>/marketplace/api/v1/app/model/?offset=2&amp;limit=2&amp;format=xml</next>
      <total_count type="integer">4117</total_count>
      <previous type="null"/>
      <limit type="integer">2</limit>
      <offset type="integer">0</offset>
  </meta>
</response>

Representations for single model instances (selected using the primary key) do not have the objects element:

<?xml version="1.0" encoding="utf-8"?>
<object>
  <field_name>field value</field_name>
  <field_name2 type="boolean">True</field_name2>
</object>

As you can see, a “type” attribute is added to the field element in cases where the value is not a simple string. This allows the field to be specified as null for example.

JSON

JSON representations store pagination metadata about object sets into a meta object stored at the root level.

JSON representations follow this reference example:

{
  "meta": {
      "limit": 20,
      "next": "/marketplace/api/v1/app/model/?offset=2&limit=2&format=json",
      "offset": 0,
      "previous": null,
      "total_count": 4117
  },
  "objects": [
    {
      "field_name": "field value",
      "field_name2": true
    },
    {
      "field_name": null,
      "field_name2": false
    }
  ]
}

Representations for single model instances are very simple and follow this example:

{
  "field_name": "field value",
  "field_name2": null
}

JSON-P with provided callback

JSON-P representations can be generated by providing a callback function name as a GET parameter. JSON-P is exactly the same as standard JSON but with the callback wrapped around the JSON.

For example, the GET request for http://yoursite.com/marketplace/api/v1/app/model/?format=jsonp&callback=myCallback would result in a response equivalent to the following:

myCallback({
  "meta": {
      "limit": 20,
      "next": "/marketplace/api/v1/app/model/?offset=2&limit=2&format=jsonp&callback=myCallback",
      "offset": 0,
      "previous": null,
      "total_count": 4117
  },
  "objects": [
    {
      "field_name": "field value",
      "field_name2": true
    },
    {
      "field_name": null,
      "field_name2": false
    }
  ]
})

Home

Browse

Glossary

You are here:

This Page