Formatting

Wire Formats

The AgileZen API can communicate in two wire formats, JSON and XML. The format for input and output is controlled via the use of HTTP headers, specifically Content-Type and Accept. To refer to the formats, you use their internet media type, also called MIME types:

Desired Format	Media Type
XML	application/xml
JSON	application/json

If you don’t specify a wire format, AgileZen will speak JSON by default.

Incoming Information

The wire format of incoming information (which you send to AgileZen via POSTs and PUTs) is controlled by the Content-Type header. If the Content-Type header is not set, the Accept header is considered instead. If the Accept header contains either the XML or JSON media type, AgileZen will return data in that format.

Content-Type Value	Accept Value	Expected Format
application/xml	(anything)	XML
application/json	(anything)	JSON
–	application/xml	XML
–	application/json	JSON
–	–	JSON

The net result of this behavior is that, by default, AgileZen will always respond in the same language that you speak to it. For example, if you send AgileZen XML, it will respond with XML, unless you tell it otherwise.

Outgoing Information

The wire format of outgoing information (which AgileZen returns to you after every request) is controlled by the Accept header. If the Accept header doesn’t contain either the XML or JSON media type, the Content-Type header is considered instead. If the Content-Type header is set to either the XML or JSON media type, AgileZen will return the data in that format.

Content-Type Value	Accept Value	Expected Format
(anything)	application/xml	XML
(anything)	application/json	JSON
application/xml	–	XML
application/json	–	JSON
–	–	JSON

As described above, the net result of this behavior is that, by default, AgileZen will always respond by the same language that you speak to it. For example, if you send AgileZen XML, it will respond with XML, unless you tell it otherwise.

URL-Based Content Negotiation

For situations where you can’t use HTTP headers, AgileZen also supports URL-based content negotiation. To request a specific format, you can add an extension to the URL. For example, accessing the following URL will return the list of stories in project 1 in XML:

https://agilezen.com/api/v1/projects/1/stories.xml

The available extensions are, as you might expect:

Extension	Format
.xml	XML
.json	JSON

If you specify an extension in the URL, it overrides all headers passed in for both incoming an outgoing information.

JSONP Support

The AgileZen API has support for JSONP responses. JSONP is a simple mechanism primarily used to get around the same origin policy to which XMLHttpRequest (XHR) calls are subject. A JSONP response is just a normal JSON-encoded response, wrapped in a callback function. Rather than requesting the resource via XHR, the resource is specified as the src attribute of a script tag. When the browser loads the resource, it interprets the JSON-encoded response into a JavaScript object, and passes it to the callback function.

To trigger a JSONP request, just specify the name of the callback function that you’d like to be called via the callback query string parameter. For example:

<script type="..." src="https://agilezen.com/api/v1/projects?callback=SomeCallback&apikey=..."/>

AgileZen will respond like this:

SomeCallback({ /*...JSON-encoded response here...*/ })

While it can be a useful hack, JSONP has its limits. It only works for read operations (endpoints that support the GET verb), and you must specify your API key as a parameter in the query string. If you’re using JSONP solely to get around the XHR same origin policy, we strongly encourage using Cross-Origin Resource Sharing instead.

Response Compression

The AgileZen API supports compression of responses in two formats, GZip and Deflate. To request that a response be compressed using one of the two formats, you can specify a value for the Accept-Encoding header during your request.

Accept-Encoding Value	Response Compression Format
gzip	GZip
deflate	DEFLATE

By default, AgileZen will respond with an uncompressed response.

Human-Readable Responses

By default, AgileZen removes all unnecessary whitespace from its responses to reduce their size. This can make it difficult to read during debugging. If you’d like AgileZen to format its responses in a human-readable way, you can do so in a couple of ways.

The preferred way is to set the value of the X-Zen-ApiIndent header to true in your requests. For example:

GET /api/v1/projects
...
X-Zen-ApiKey: 9aae75efd6b3470db8abd15b61c55cef
X-Zen-ApiIndent: true
...

Another option is to use the indent parameter. For example, to return a list of projects in a human-readable format:

https://agilezen.com/api/v1/projects?indent=true

This parameter works for both XML and JSON responses. (Note: all of the examples shown in this documentation are formatted as though they were requested with human-readable formatting enabled.)

Data Types

Dates and Times

Timestamps are returned in Coordinated Universal Time (UTC), formatted per the ISO 8601 specification:

yyyy-mm-ddThh:ii:ss

For example, 2:30:45 PM UTC on January 15th, 2011 would be represented as:

2011-01-15T14:30:45

Time Spans

Time spans (durations) are returned in the nearest whole number of seconds.