Clarizen REST API Version 2.0

 

Developer's Guide

 

 

What's inside:

• GETTING STARTED
• Version 2.0
• New features

• Moving from Version 1.0 to Version 2.0

• Introducing the CLARIZEN REST API

• Supported Editions

• REST API Basics

• Compression

• Services

• Authentication

• Metadata

• Data

• Bulk

• API Calls Basics

• Synchronous Execution of the API

• Auto Commit Policy

• Error Handling

• Session Management

• Session Timeout

• Session Number Limits

• Licensing

• API Governance

 

 

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.
• Integrations with Desktop tools: create integrations with desktop authoring tools to bring task management closer to the employee's desktop
• Integrations with legacy systems:  create integrations with your internal data management systems to exchange relevant data and perform on the fly integrations.

 

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 try to 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-Picklist 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.

Metadata — Provides information about the Clarizen data model including supported entities, entity fields and data types, as well as relations between entities.

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/

 

Authentication

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

 

Metadata

The Metadata service provides methods to interrogate the Clarizen data model.

You can use this service to 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 following example retrieves the description of all entities in your organization

 

//Get a brief description of all types in the account

curl https://../services/metadata/describeMetadata

{

  "entityDescriptions": [

  {

    "typeName": "Note",

    "validStates": [],

    "label": "Note",

    "labelPlural": "Notes",

    "parentEntity": "Comment",

    "displayField": "Name"

  }

...

}

 

//Get a full description of the WorkItem type including field and relation information

curl https://../services/metadata/describeMetadata? typeNames=WorkItem&flags=relations,fields

{

  "entityDescriptions": [

    {

      "typeName": "WorkItem",

      "fields": [

      {

        "name": "CreatedBy",

        "referencedEntities": [

          "User"

        ],

...

}

 

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, that when retrieving 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) 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 (e.g. in the example above 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 Timeouts
• 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 timeouts 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).

 

Licensing

Regular application written using Web Services API requires Standard Clarizen license.

Recommendation: You can create special user that will play the role of the “Web Service” user in a non-interactive applications and assign him a standard Clarizen license.  Use this user’s credentials to login into non interactive application. Be sure that you treat correctly Session tine out case in non-interactive applications.

 

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.

   Note:  Each call made from a client to our web service is counted as an API call. If a single call to the web service performs several operations it will still be counted as 1 API call.