REST API Guide Version 2

Avatar
Clarizen
Follow

REST API Guide Version 2

Developer's Guide

What's inside:

GETTING STARTED

Clarizen provides programmatic access to your organization information using a simple and powerful REST API.

Using the Clarizen REST API you are able to develop various types of applications, such as:

  • Custom applications: create custom applications to gain additional benefits for your organization using business data located in the Clarizen repository. Provide your employees with specific and familiar User Interface for specific organizational processes
  • Integration with Desktop tools: create integration with desktop authoring tools to bring task management closer to the employee's desktop
  • Integration with legacy systems: create integration with your internal data management systems to exchange relevant data and perform on the fly integration

API VERSION 2.0

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 Clarizen
  • 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

INTRODUCING THE CLARIZEN REST API

REST API access is enabled for all Enterprise organizations and does not require a special key to access the API.

Certified partners who develop applications that need to work for Professional edition organizations as well can request a partner ID to access the API. Please contact us for more information.

Supported Editions

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

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

REST API Basics

Clarizen REST resources are divided into several core services: Authentication, Metadata, Data and Bulk. The base URL for all REST API calls is https://api.clarizen.com/v2.0/services/ .
Each core service resides under the base URL so, for example, calls that are part of the Authentication service will reside under https://api.clarizen.com/v2.0/services/authentication.
Some resources support multiple HTTP methods (i.e. GET, POST, PUT and DELETE) to perform different operations on the same resource (such as retrieving an entity vs updating an entity) and some resource support only a single method (i.e. GET only). The supported format for both requests and responses is JSON.

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.

Services

Authentication — Provides the basic calls to authenticate with the REST API, get session information and access the correct data center where your organization is located.

Data — Provides the calls to create, update, retrieve and delete objects in Clarizen as well as to query and search for objects.

Bulk — Allows clients to perform bulk operations.

A complete list of all services and API calls supported is available at https://api.clarizen.com/v2.0/services/

For picklists, you can find available values in the REST Metadata API Reference Guide, which is available here:

Authentication

See also API Keys Support

The Authentication service is the starting point for all applications working with the Clarizen REST API.
The basic sequence to start working with the API is to first determine in which Clarizen 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 Clarizen. The basic data element in Clarizen 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.

API Calls Basics

Using API calls you can perform specific operations applied to the Clarizen entities and metadata. Using API you can:

  • Login into the system
  • Add, update, delete entities that belong to different entity types
  • Query entities from different entity types
  • Retrieve administrative information
  • Other

Synchronous Execution of the API

Execution of API requests is synchronous.  API request is submitted by the client application to the Clarizen Web Service, Clarizen 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.

Error Handling

The REST API returns error data that can help you to identify erroneous situations occurring during the execution of an operation. When an API calls succeeds, an HTTP 200 response is returned and the response body contains the result of the call. In case of error, an HTTP 500 response is returned and the response body will contain an error object such as the following:

{
"errorCode": "SessionTimeout",
"message": "Your session has expired",
"referenceId": "VuRekGz2wEWuyb6lk6XTrA"
}

If you encounter an “Internal Error” and need to consult with Clarizen support, please make sure to include the value from the “referenceId” field to make sure your request can be easily tracked within our system.

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

Session Timeout

Similar to the UI, Web services sessions automatically time-out after 10 minutes of inactivity, requiring a login to resume activity. However, if the client submits a request the inactivity time is reset.

Note : For security reasons, we recommend that you close your session using the Logout operation as soon as you are done using the service.

If you explicitly logout of a session, and then attempt to utilize the same session, a SessionTimeout error code is returned. Your code should be prepared to handle session timeout by re-login when a session timeout occurs.

If you need to eliminate open sessions for security reasons, you should call logout upon completion of an operation.

Session Number Limits

Number of the concurrent sessions authenticated with the same user credentials is limited to two (2).

Metadata Explorer

The Metadata Explorer service provides methods to interrogate the Clarizen API. You can login to this service and get a list of entity types available to your organization and to get a detailed description of the fields available on each entity type. 

The Metadata Explorer is available through:

Metadata_Explorer.png

API Governance

In order to optimize performance of the Clarizen application and database servers, Clarizen API engine provides several mechanisms to control consumption of the processes initiated by the API. These mechanisms monitor and control requests from the REST API to ensure that the user experience is not extensively impacted by the possible heavy processes and the burden of the Web services is shared among all users.

API Governance is made up of following areas:

  • Request batch limiting: The total number of requests that can be processed in one call to the web service is 100
  • Request limiting: The total size of the requests sent in one call to the web service must not exceed 25 MB
  • Call limiting: 1,000 API calls per paid license per day with a maximum of 1,000,000 calls per day
  • Rate Limiting: Rate limiting allows up to 25 requests per second. The quota is global for the organization, and not per user
    Notes:
    • A bulk request (multiple calls in a single request) is supported, however depending on its position in the queue, subsequent calls may not go through
    • Internal tools and apps, for example, DataLoader and Doc Publisher are excluded from the quota

Note: Each call made from a client to our web service is counted as one API call. An exception is the Bulk request, used for executing several API calls in a single call. Each inner request used in the Bulk request is counted as one API call.

Have more questions? Submit a request

Comments