Formatting

The Zen API can communicate in two wire formats, XML and JSON. 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 MIME types:

If you don't specify a wire format, Zen will speak XML by default.

The wire format of incoming information (which you send to Zen 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 MIME type, Zen will return data in that format.

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

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

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

By default, Zen removes all unnecessary whitespace from its responses to reduce their size. This can make it difficult to read during debugging. If you'd like Zen to format its responses in a human-readable way, you can do so via the indent parameter. For example, to return a list of projects in a human-readable format:

http://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 returned with the indent parameter set to true.)