New Features

The following capabilities were added to the API in v2:

• CZQL — A new query language to easily perform queries via the API. CZQL supports all the query operators previously available via the EntityQuery API and also the new AggregateQuery capabilities. Complete documentation of CZQL is available here
• AggregateQuery — Provides the ability to aggregate and group results using standard grouping functions like Count, Sum, etc.
• RelationQuery — Provides the ability to query the related items of an entity
• Search — Perform full text search queries in a specific entity type or across all entities
• UpdateImage — Update the image of an object in AdaptiveWork
• Download\Upload — An easier way to download and upload files, up to 5MB, as well as enhanced performance when uploading or downloading large files
• Metadata — The Metadata API has been simplified and no longer requires multiple calls to obtain the entire metadata information. New options have been added to allow selecting which information to return in order to improve the response time
• StreamedQuery — A query API that allows returning very large data-sets in an efficient way. Using the StreamedQuery API you can retrieve the entire query result list in a single call

Moving from v1.0 to V2.0

We maintain backward compatibility whenever possible between API versions. The following breaking changes have been applied in API v2:

• Authorization info should not be sent via cookies. Instead the Session ID must be sent in the standard Authorization header (See here for more information)
• The API for uploading and downloading files has been changed. See the reference guide for more details
• When creating a Milestone object, you must pass an existing parent (Previously it was possible to create a milestone and only later attach it to a parent)
• The Metadata API returns more detailed information about the different field types. Two new field types have been added: Multi-Pick list and Binary
• Paging was changed. Instead of transferring PageNumber and PageSize parameters, you now need to send the From and Limit parameters which allows more flexibility. If you followed the API best practices of taking the Paging object from a query result and pass it “as-is” to the next request, then no changes are required

Supported Editions

REST API is provided for AdaptiveWork V6 and on. To use the REST API your organization must use Enterprise Edition. If you are already a customer of AdaptiveWork and do not have the enterprise edition, please, contact your sales representative.

Business and development partners of AdaptiveWork can use the Developer edition. AdaptiveWork's developer edition provides access to all functions available in the Enterprise edition.

Compression

The REST API supports compression on both requests and responses. It is strongly recommended to pass an “Accept-Encoding: gzip“ header on every request so responses from the server will be compressed. Clients that support compressed requests can compress request body and add a “Content-Encoding: gzip” header to indicate the requests are compressed.

Authentication

See also API Keys Support

The Authentication service is the starting point for all applications working with the AdaptiveWork REST API.
The basic sequence to start working with the API is to first determine in which AdaptiveWork data center your organization data is located, then perform a login operation to that data center to receive a Session ID.
The Session ID is returned in the response body, each additional request should send this session ID back to the server in an "Authorization" header with the “Session” prefix in order to reuse the same Session. The following example shows the basic sequence of operations using cURL:

//Contact the login server to get the URL of your data center
curl -d '{userName: "user", Password: "****"}'  https://api.clarizen.com/v2.0/services/authentication/getServerDefinition
{
"serverLocation": "https://api2.clarizen.com/v2.0/services"
}
//Perform the login operation on the correct data center
curl -d '{userName:"user",password:"****"}' https://api2.clarizen.com/v2.0/services/authentication/login
{
"sessionId": "1234567-0106-42c8-9b85-cfb76971c0ff",
"userId": "1234567-1bf5-4c4a-baf1-ea42b0417284",
"organizationId": "1234567-09b3-4447-820f-f7102d6835c3",
"serverTime": "2014-01-01T20:15:05.2954874Z",
"licenseType": "Full"
}
//Pass the sessionID in the Authorization header for all future requests
curl -H "Authorization: Session 1234567-0106-42c8-9b85-cfb76971c0ff" https://api2.clarizen.com/v2.0/services/authentication/GetSessionInfo

See also API Keys Support

Data

The Data service contains most of the functionality available via the REST API which is to Create, Retrieve, Update and Delete data in AdaptiveWork. The basic data element in AdaptiveWork is an Entity which is accessible via the /services/data/objects/ {typeName} / {id} URI where typeName is the Entity Type (e.g. Project or Issue} and id is the id of that entity. This URI can be used to perform the basic 4 CRUD operations via the following respective HTTP methods: PUT, GET, POST and DELETE. The following examples show how these methods can used on an entity of type “Issue”

//Create an issue without giving it an explicit id and
curl https://../services/data/objects/issue -X PUT -d "{title: 'Issue 1'}"
{
"id": "/Issue/56bdfa2b-f737-4b50-9de6-62933e5284ca"
}
//Retrieve the CreatedOn and CreatedBy (along with the name of the creator)
curl https://../services/data/objects/Issue/56bdfa2b-f737-4b50-9de6-62933e5284ca?fields=CreatedOn,CreatedBy,CreatedBy.Name
{
"id": "/Issue/56bdfa2b-f737-4b50-9de6-62933e5284ca",
"createdOn": "2014-04-06T10:26:14.2291260",
"createdBy": {
"id": "/User/340c6d9a-1bf5-4c4a-baf1-ea42b0417284",
"name": "Sam"
}
}
//Update the priority field
curl https://../services/data/objects/Issue/56bdfa2b-f737-4b50-9de6-62933e5284ca -X POST -d "{priority: 5}"
{}
//Delete the issue
curl https://../services/data/objects/Issue/56bdfa2b-f737-4b50-9de6-62933e5284ca -X DELETE
{}
//Query all the issues created after a certain date ordered by creation date
curl https://../services/data/EntityQuery -d "{
typeName: 'Issue',
fields: ['createdOn','title'],
orders: [{fieldName: 'createdOn', order: 'Ascending'}],
where: {
_type: 'Compare',
leftExpression: {fieldName: 'createdOn'},
operator: 'GreaterThan',
rightExpression: {value: '2014-04-03'}
}
}"
//Perform the above query using CZQL
curl https://../services/data/query?q=SELECT createdOn,title FROM Issue WHERE createdOn>2014-04-03

Note: In the above example, when a field of an object which is a reference to another object (e.g. in the case above, retrieving the creator of an issue which is a reference to a ‘User’ entity) is retrieved, the returned value is itself an object with fields. The default field that is retrieved for reference fields is the ‘Id’ field but you can ask for other fields by using the “.” (dot) notation. See in the example above where the CreateBy.Name field is requested.

Bulk

The bulk service allows clients to perform several API calls in a single HTTP round trip. The bulk service can be used in two scenarios:

1. Performance optimization
2. Overcoming HTTP limitations

The bulk service exposes a single Execute operation which accepts an array of “Request” objects and returns an array of “Response” objects. Each request represents a single REST API call and has the following properties: Url, Method and Body. Each response has a StatusCode and Body. For example, to update the ‘StartDate’ and ‘DueDate’ of a task and immediately retrieve the updated ‘Duration’ of that task, the following request can be performed:

//Execute two request in one round trip using the execute message
curl https://../services/bulk/execute -d "{requests:[
{
url:'/data/objects/task/9836f5ee-e539-4b39-bfa5-87fb862397be',
method: 'POST',
body: '{startDate: \"2014-04-20\",dueDate: \"2014-04-25\"}'
},
{
url:'/data/objects/task/9836f5ee-e539-4b39-bfa5-87fb862397be?fields=duration',
method: 'GET'
}
]}"
{
"responses": [
{
"statusCode": 200,
"body": {}
},
{
"statusCode": 200,
"body": {
"id": "/Task/9836f5ee-e539-4b39-bfa5-87fb862397be",
"duration": {
"unit": "Days",
"value": 5.0,
"durationType": "Default"
}
}
}
]
}

The bulk execute operation is also useful in cases where performing a regular HTTP GET operation might exceed the limitations of Url lengths. In these cases, the operation can be performed inside a bulk operation without these limitations to the request size.

Synchronous Execution of the API

Execution of API requests is synchronous. API request is submitted by the client application to the AdaptiveWork Web Service, AdaptiveWork processes request and returns relevant response. Client application should wait for response on submitted request. Asynchronous requests are not supported.

Auto Commit Policy

Every request that is submitted by the client application is automatically committed. All operations, such as Create, Update and Delete are treated as a separate transaction. Client application does not need to send explicitly Commit statements.

It is recommended that client application will avoid situation when several operations should be handled as one transactional package. If impossible, such situations should be handled by the client application specifically. For example, if there are two consequent operations that should be both performed successfully and the second operation failed, application must “roll back” itself results of the first operation.

Session Management

After a user was successfully authenticated, the system generates a random and unique identifier known as the Session ID. This identifier is returned to the client as part of the Login return value and the client must pass this Session Id on subsequent requests (See the authentication section for details on how to pass the session ID)

A session lifetime is controlled by

• Session Timeout
• Sessions Numbers Limit