Clarizen REST API Version 1.0

 Version 2.0 is available, please see  https://clarizen.zendesk.com/entries/89516637-Clarizen-REST-API-Version-2-0

Developer’s Guide

 

 

WHAT'S INSIDE:

• GETTING STARTED
• Introducing the CLARIZEN REST API
• Supported Editions
• REST API Basics
• Compression
• Services
• Authentication
• Metadata
• Data
• Bulk
• API Calls Basics
• Error Handling
• Session Management
• 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 will be able to develop various types of the applications, such as:

•         Custom applications: create custom application to have additional benefits of your organization and business data that resides in the Clarizen repository. Provide your employees with specific familiar User Interface for specific organization processes.
•         Integrations with Desktop tools: create integrations with desktop authoring tools to bring task management close to the employee desktop
•         Integrations with legacy systems:  create integrations with your internal data management systems to exchange relevant data.

 

INTRODUCING THE CLARIZEN REST API

REST API access is enabled for all Enterprise organizations. Certified partners can request a partner Id to access Clarizen’s REST API. Please contact your sales representative or Clarizen technical support for more information.

 

Supported Editions

 

REST API is provided beginning from version V6 of Clarizen. To use the REST API your organization must use Enterprise Edition. If you are already customer of Clarizen and do not have this edition, please, contact your sales representative.

 

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

 

REST API Basics

Clarizen REST resources are divided to several core services: Authentication, Metadata, Data and Bulk. The base URL for all REST API calls is  https://api.clarizen.com/v1.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/v1.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, and 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 the services and API calls supported is available at  https://api.clarizen.com/v1.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 both as an HTTP Cookie and in the response body. Each additional request should send this cookie back to the server 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/v1.0/services/authentication/getServerDefinition

{

  "serverLocation": "https://api2.clarizen.com/v1.0/services"

}

 

//Perform the login operation on the correct data center

curl -d '{userName:"user",password:"****"}' https://api2.clarizen.com/v1.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 a USID cookie in all future requests

curl --cookie USID=1234567-0106-42c8-9b85-cfb76971c0ff https://api2.clarizen.com/v1.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 list of entity types available for your account and de

 

//Get the list of entity types available for your organization

curl https://../services/metadata/ListEntities

{

  "TypeNames": [

    "EmailRecipient",

    "Email",

    …

    "Organization"

   ]

}

 

//Describe the WorkItem and Issue entity types

curl https://../services/metadata/describeEntities?TypeNames=WorkItem,Issue

{

  "entityDescriptions": [

    {

      "typeName": "WorkItem",

      "fields": [

        {

          "name": "CreatedOn",

          "type": "DateTime",

          "presentationType": "Date",

…

}

 

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'}

                                }

                }"

               

 

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.