Agilefant has a RESTful API that is currently in public BETA. While not all of Agilefant’s functionality is available via the API, most day-to-day operations, such as listing, creating, updating, deleting stories and tasks can be accomplished.

URL Structure

All API access is done over https at https://cloud.agilefant.com/<account name>/api/v1/. For example, in the url https://cloud.agilefant.com/example/api/v1/tasks/5 the path segments have the following meanings:

  • example means that we are using the API for organization with the name “example”
The API is strictly separated by account (Organization) on an url level. What this means that instead of “one” Agilefant API, each organization have their own API and url space.
  • v1 means that we are using API version v1
  • tasks means we are access task resources
  • 5 means that we are accessing a resource with the id 5

Schema

All objects are sent and received as JSON. In object properties, value null means empty or not defined. If a property is omitted (i.e. undefined) it means that the property is not included in the response by design, or that the client is not authorized to see it.

All returned objects have a property ‘type’ that identifies the type of object, values begin with lowercase, e.g. ‘task’, ‘story’, etc.

Timestamps are sent and returned as strings in ISO 8601 format.

In JSON objects submitted in request body, only the types and ids of nested objects matter, e.g.:

{
	type: 'task',
	id: 123,
	parent: {
		type: 'story',
		id: 456,
		name: 'New Parent' // THIS WILL BE IGNORED
	}
}

can be used to move a task to a different story, but it does not set the new parent story’s name.

Template Objects

The various rest endpoints return object trees in JSON format. The shape of the tree is determined by so called Templates, whose names are supplied with the call as a query parameter (this “templates” parameter is needed to retrieve anything besides ids). If multiple templates are supplied, those are merged together. For example, if we had a template called ‘ParentName’:

{
	type: 'task',
	id: 0,
	parent: {
		type: 'story',
	    id: 0,
	    name: ''
	}
}

And we would fetch a task using this template:

https://cloud.agilefant.com:443/dev/api/v1/tasks/123?templates=ParentName

We would get back a JSON object containing:

{
	type: 'task',
	id: 123,
		parent: {
	    type: 'story',
	    id: 456,
	    name: 'The name of the parent'
	 }
}

Other properties for the task itself and the parent would be omitted (except type and id which are always included) as they are not listed in the template. Allowed template names are determined by resource type, and are listed with each resource endpoint of the list of resources tab.

Bulk Operations

By default, all operations that can be performed on one resource, can be performed on multiple resources at the same time. For get operations this means that path segments that list specify what to fetch can contain multiple comma or semicolon separated ids. For example:

https://cloud.agilefant.com:443/dev/api/v1/tasks/123,456?templates=Details

will retrieve tasks 123 and 456.

For post operations, the request body is an array of JSON objects that are to be created or updated.

Authorization

Authorization in the Agilefant API is done using the Http Basic Auth header. However, the server does not send www-authenticate header to avoid pop-ups and to reduce the risk of CSRF attacks. While this means that the API is not explorable directly by browser, it can be explored using the tool on the list of resources tab.

Response Codes

API uses a subset of HTTP status codes as described below:

Success

  • 200: Operation was successful.
  • 201: Resources were created as a result of POST or PUT operation.

Error

  • 400: Server was unable to deserialize the provided JSON.
  • 401: Authorization credentials were invalid or not supplied.
  • 403: User is not authorized to carry out the operation.

Redirects

Redirects are currently not in use, but we reserve the right to add those in the future, so redirects should be followed.

CORS Support

CORS support is currently not available

Resources in the Agilefant API are listed below.

To access the resources using the test interface within each resource, you first need to login to an Agilefant Cloud account. Pleate note that for security reasons login credentials are not stored. This means that if you navigate away from this page you need to login again.

Login successful!
Login failed!
Can’t read from server. It may not have the appropriate access-control-origin settings.