GET query specifications

GET queries are used to retrieve a specific set of items from Agile Manager.

This topic provides specifications for Queries, Pagination, Fields, and Ordering (Sorting). Within in each syntax description below, click hyperlinks links to drill down for further details.

The following is an example of a full query within a GET request.

http(s)://…/agm/api/workspaces/1000/releases?query=”id>1001”&order-by=end_date&fields=id,name,end_date&offset=1&limit=3

This example returns releases with IDs greater than 1001 from the default workspace (workspace ID = 1000).

The releases returned are sorted in ascending order, by the release end date.

The fields included in the data are limited to the release ID, name, and end date.

Only three releases are returned, starting from the second release in the workspace.

Queries

Each query consists of a query statement.

  • Query statements are surrounded in double-quotes ("), and consist of one or more query phrases and any relevant logical operators.
  • You must have at least one query phrase in each statement. If you add additional query phrases, you must add a logical operator before each one.

Use the following query syntax:

The following example shows a query statement that includes multiple query phrases.

http://.../backlog_items?query="id>100;status='open';(rank>10||rank<20)"

This example returns all backlog items that have an ID greater than 100, who's status is Open, and are ranked between 10 and 20.

Back to top

Pagination

Pagination allows you to retrieve a limited collection of results from Agile Manager, as well as an offset of results.

Note: In the response, the Data section includes only items defined by the offset and limit values.

However, the TotalResults value reflects the entire number of items returned from the query, without the offset and limit.

The following example returns 10 domains, at places 40-49:

*** Request *** 
GET /backlog_items?offset=40&limit=10 
Accept:             application/json 
Host:               agm.com:8080 
 
*** Response *** 
HTTP/1.1200 OK 
Content-Encoding:   gzip 
Content-Type:       application/json;q=0.9 
Date:               Mon, 27 Mar 201412:11:05 GMT 
Server:             Jetty(7.5.4.v20111024) 
{ 
	"data": [ 
		... 
	], 
 "TotalResults":40
}

Pagination keywords include:

Back to top

Fields

Query fields allow you to limit the set of fields returned with the results, using the following syntax:

fields=<field name>[[,<field name>]]

Field names must be separated by commas (,)

Some fields are always returned, including: type, subtype, and id

If no fields are defined, all of the fields for the specified resource are returned.

Tip: To view the full list of fields for an entity submit a GET operation for that entity.

The following example shows a set of fields.

The data returned with this query will include details about the rank, name, and end_date fields only, in addition to the fields which are always returned.

fields=rank,name,end_date

Back to top

Ordering (Sorting)

Allows you to sort a collection of results retrieved, using the following syntax:

order-by=[<direction>]<field name>[[,[<direction>]<field name>]]
 

By default, results are sorted in ascending order. This default is used whenever the direction is left empty.

Use a minus sign (-) to sort results in descending order.

The following example shows a query that will return items sorted:

  • First by name, in ascending alphabetical order;
  • And then sub-sorted by status, in descending order.
http://.../backlog_items?order-by=name,-status

Back to top