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.
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:
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:
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:
Like entity resources, container resources can be hierarchical as well. For example, the list of stories in project 123 is accessible at this URI:
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.
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:
|GET||Retrieve the entity or container||X||X|
|POST||Create a new entity within a container||X|
|PUT||Update an existing entity||X|
|DELETE||Delete an existing entity||X|
This is just a general guideline – the documentation for each individual endpoint describes which verb(s) it supports.
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:
If you’re in a situation where you can’t actually send a
PUT, you can send this
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.