Overview

The JSON API allows third party developers to access core functionality without the need to use the web interface. The API exposes a wide variety of methods for both reporting on the system, and performing actions.

We highly recommend that you also sign-up to use the Developer Exchange, which is a free resource for all integrators and users of the API to ask questions or learn from worked examples.

The API requires a separate module to be included in your licence key. Please see the price list for more details.

API documentation

The methods available in the Chorus JSON API are documented in /apidocs.html under your instance. For example, if your Chorus instance has the address https://example.chorus.thirdlight.com, then you can find the API documentation under https://example.chorus.thirdlight.com/apidocs.html.

Endpoint Address

The JSON request uses JavaScript notation to pass the arguments to the Chorus API endpoint, which is: /api.json.tlx.

For example, if your site is https://example.chorus.thirdlight.com then the endpoint is https://example.chorus.thirdlight.com/api.json.tlx.

Requests are typically sent using HTTP POST to this endpoint.

Forming the JSON

The API documentation is expressed in function prototypes. This is to allow a neutral definition of the API to be provided, without assuming any particular language. Bindings for popular languages are expected to be published in order to make using the API convenient in native functions, e.g. in Python, Go and PHP. At present,  the underlying API interface is JSON.

If you are viewing the Chorus function prototypes, you can convert them to JSON requests. In this example, we will take the definition of the Core.Login() method, and build a JSON request which provides the necessary arguments, then post that JSON the Chorus API. You can use this example to obtain a session ID, which is needed for almost all API requests, so this will generally be one of the first API calls made.

The documentation for the Core.Login() method is found in the documentation under the 'Core' module. You can reach it here: /apidocs.html#Core_Login:

The options hash supports keys as follows:

	persistent - allow the session to endure beyond the normal limit
	elevated - log in with all available administrative permissions (default prior to API v2.0)
	restricted - log in without administrative permissions (default since API v2.0)

The returned hash will contain keys as follows:

	sessionId - a session identifier which should be used in all further communication
	userDetails - a hash containing user informationtype - the type of entity logged into the system. Normally this will be 1, indicating a conventional user
	username - the login username
	description - name or description
	email - email address
 

To interpret this as JSON, first we construct a standard JSON request for the Third Light API. State the method using an 'action' and pass in the function arguments under 'inParams'.

REQUEST:
 
{  
   "apiVersion":"2.0",
   "action":"Core.Login",
   "inParams":{  
      "username":"exampleusername",
      "password":"MySecretPassword"
   }
}

The username string and password string have been passed to the Core.Login "action" as strings.

if the username and password are correct, this API call will return a response in JSON, as follows:

{  
   "result":{  
      "api":"OK",
      "action":"OK",
      "timings":{  
         "initTime":40,
         "setupTime":0.8,
         "innerMethodTime":997.4,
         "methodTime":1004.2,
         "totalTime":1045
      }
   },
   "sideLoad":[  

   ],
   "outParams":{  
      "sessionId":"90K0cEBy2BS,mOmFMmATsz8zqQBJ3pLx",
      "userDetails":{  
         "type":1,
         "userref":"1-64",
         "domain":"dom0",
         "id":"64",
         "username":"tlps",
         "authMode":"password",
         "hasRecycleBin":true,
         "primaryGroupGuid":null,
         "ftpServer":"example.chorus.thirdlight.com",
         "ftpUsername":"example_tlps",
         "isSystemTZ":true,
         "locale":"en_GB",
         "mustChangePass":false,
         "elevated":false,
         "isImpersonated":false,
         "canElevate":false,
         "isEditable":false,
         "guid":"9516410c-75da-11e7-b270-000c29ae5fc6",
         "gtype":1,
         "seqno":3,
         "created":"1501496732",
         "modified":"1501496764",
         "objectType":"USER_DETAILS",
         "name":"tlps",
         "description":"TLPS test user",
         "timeZone":"Europe\/London",
         "customInitials":"TLPS",
         "customAvatarColor":null,
         "email":"[email protected]",
         "abilities":{  
            "ManageSite":false,
            "objectType":"USER_ABILITIES"
         },
         "primaryGroupId":null,
         "avatar":"https:\/\/example.chorus.thirdlight.com\/avatar.tlx\/1kP.ibW1k1k.1f35E1kPSx87.png",
         "initials":"TLPS",
         "defaultInitials":"T",
         "avatarColor":"#F16C20",
         "defaultAvatarColor":"#F16C20",
         "usingCustomAvatar":false,
         "quota":"0",
         "backingFolderId":"43524499733",
         "backingFolderGuid":"951ed042-75da-11e7-b270-000c29ae5fc6",
         "subtreeQuota":"0",
         "context":"me"
      },
      "objectType":"LOGIN_DETAILS"
   }
}

In the JSON, you can obtain the returned hash (containing the sessionID, userDetails hash, username, description and email variables noted in /apidocs.html). They are provided under the outParams element in the JSON response. You can access these elements from your chosen language in order to make use of them, or you can simply extract and use the value of "sessionID", which is the most important part of the response.

Note that if the username is not found (or the password is wrong), the response will be similar to this:

RESPONSE:
 
{  
   "result":{  
      "timings":{  
         "initTime":69,
         "setupTime":2.2,
         "innerMethodTime":29.5,
         "methodTime":46.1,
         "totalTime":117.3
      },
      "api":"OK",
      "action":"USER_NOT_FOUND"
   },
   "correlationId":"9781c9ce-f245-4f2b-bbf0-7f6e924ebad7"
}

Passing optional parameters to an API method

The Core.Login() method includes an "options" hash, which by default is NULL. This means that any options are left as their defaults. However, if you do wish to pass in options to this method, then you can add an options hash to the JSON request. For example, say we want to allow the session to endure beyond the normal limit (i.e. to avoid timeouts on the session which might be inconvenient for our intended use). To do this, we can set 'persistent' to be true:

REQUEST:

{  
   "apiVersion":"2.0",
   "action":"Core.Login",
   "inParams":{  
      "username":"exampleusername",
      "password":"MySecretPassword",
      "options":{  
         "persistent":true
      }
   }
}