AgileZen API Documentation

Overview

The AgileZen API is designed around a concept called REST. In a RESTful system, information is organized into resources, each of which is uniquely identified via a URI.

Resources

Assuming you’ve used the product, examples of resources in AgileZen are what you might expect: projects, stories, tasks, comments, etc. Resources are organized into two basic types: entity resources and container resources.

Entity Resources

An entity resource refers to a single piece of information in AgileZen, like a project or a story. Every entity is identified by a unique numeric identifier which shows up in entity resources’ URIs. For example, a project with the identifier 123 would be referenced by this URI:

https://agilezen.com/api/v1/projects/123

Some URIs are built on top of others to indicate a parent-child relationship between resources. For example, the story 456 within project 123 would be referenced by this URI:

https://agilezen.com/api/v1/projects/123/stories/456

Container Resources

A container resource refers to a resource that contains one or more entity resources, like the list of stories in a project or the list of tags assigned to a story. Container resources have no identity of their own, and always belong to another resource. They are still referred to by URIs, however. For example, the list of your projects can be accessed by this URI:

https://agilezen.com/api/v1/projects

Like entity resources, container resources can be hierarchical as well. For example, the list of stories in project 123 is accessible at this URI:

https://agilezen.com/api/v1/projects/123/stories

Information returned by container resources is paged to avoid returning every entity in the container. You can customize these paging options by using pagination arguments.

Verbs

Different resources support different actions, which are specified by using HTTP verbs. Entity and container resources accept different verbs, as described in the chart below:

VerbDescriptionEntitiesContainers
GETRetrieve the entity or containerXX
POSTCreate a new entity within a containerX
PUTUpdate an existing entityX
DELETEDelete an existing entityX

This is just a general guideline – the documentation for each individual endpoint describes which verb(s) it supports.

Overriding Verbs

Not all browsers support all of the available verbs, and you may also encounter some difficulties if you’re behind an HTTP proxy server. To fix this issue, the AgileZen API supports the X-HTTP-Method-Override header to override the verb in your request. To use the override header, simply make a POST request with the header’s value set to the actual verb you’d like to use.

For example, updating a project requires that you send a PUT request to the URL:

https://agilezen.com/api/v1/projects/{projectid}

If you’re in a situation where you can’t actually send a PUT, you can send this POST instead:

POST /api/v1/projects/123
...
X-Zen-ApiKey: 9aae75efd6b3470db8abd15b61c55cef
X-HTTP-Method-Override: PUT
...

If you can’t send the X-HTTP-Method-Override header, you can also override the verb by sending a _method parameter, as supported by Ruby On Rails. The _method parameter can either be in the URL or in the request data – although, if you’re sending JSON or XML request data (in a PUT request, for example), you’ll need to specify it in the URL.