Third Light Developer Exchange

thirdlight

Third Light Staff

Registered: 2013-06-06

Posts: 23

Introducing the REST API

Introduction

Beginning in Chorus 2.3, Third Light has made a new REST API available for customers and integrators to use. The previous API still exists (and will continue to exist), but it does not benefit from the new guarantee that no breaking changes will be made. In other words, if you are developing a solution using our API, even as Chorus itself evolves and changes you will not need to change your code. We could not make this guarantee with the previous API, as we needed the flexibility to change the API since we use it internally.

The new REST API is designed with long term stability in mind. The API is provided via two separate interfaces: a RESTful HTTP interface, and a gRPC endpoint supported by a set of protocol buffer definitions. Both interfaces provide identical functionality, leaving the choice of which to use down to the coding task in hand.

The methods available in the Chorus REST 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.

REST interface (including Swagger) - recommended for most users

The REST interface provides simple access to all the API features, using standard HTTP semantics and JSON encoded request and response data. The REST interface is best suited to projects written for the browser, for experimental or simple projects, or simply for exploring API functionality. Requests are made using standard HTTP methods such as GET, POST, and PATCH. Request and response data is encoded using JSON.

For example, to retrieve the current environment for your Chorus site, here is a simple cURL command example:

curl -X GET "https://example.chorus.thirdlight.com/rest/v1/environment"
 
{   
    "title": "Example Chorus Site",   
    "browserTitle": "Chorus",   
    "version": "2.3"
}

The JSON request uses JavaScript notation to pass the arguments to the Chorus API endpoint, which is: /rest/v1. For example, if your site is https://{example}.chorus.thirdlight.com then the endpoint is https://{example}.chorus.thirdlight.com/rest/v1.

Requests are sent using HTTPS libraries to this endpoint.

Using Swagger

The interface can be explored using a built in Swagger UI implementation. Please visit /apidocs/swaggerui/ in your browser.

Swagger provides a great way to explore the API; you can create and test API requests in an interactive user interface that's built into Chorus, significantly reducing the time and effort needed to test and develop new code. The recommended way to use the Swagger UI is as follows:

Step 1: Click the /rest/v1/auth/login method (the description of the method will expand).

Step 2: Click on "Try it out" method:

Step 3: Update the username and password fields in the JSON body box, then click the "Execute" button (under the body box).

Step 4: Scroll down to the server response to obtain the sessionId from the response body box:

Step 5: Go back to the top of the documentation page and click the green "Authorize" button:

Step 6: Copy the session you obtained in Step 1 into the box:

Lastly, click "Authorize".

This completes the process for authenticating Swagger. All subsequent queries made inside the Swagger documentation for the Chorus REST API will now use the session automatically, and methods that need a sessionId will now been unlocked.

REST Authentication (details)

Authentication is achieved by retrieving a sessionId from one of the login methods, either auth/login or auth/loginWithKey (for API keys), and then providing that value with each subsequent request. You should obtain a sessionId and then re-use that sessionId for subsequent requests to the API. The REST interface requires the session ID to be passed in an X-Chorus-Session HTTP header.

For example, to obtain a sessionId:

curl -X POST "https://example.chorus.thirdlight.com/rest/v1/auth/login" -H "Content-Type: application/json" -d '{ "username": "jbloggs", "password": "correct-horse-battery-staple"}'
     
{
    "sessionId": "TsVYymyYvhdz3wYPB-6D-6ARrtGvCG3o",
    "userDetails": {
        "username": "jbloggs",
        "name": "Joanna Bloggs",
            ...
    }
}

The sessionId has been provided in the response (TsVYymyYvhdz3wYPB-6D-6ARrtGvCG3o).

We can now use it in subsequent API requests in the X-Chorus-Session header. In this example, we ask Chorus to provide the context for the session:

curl -X GET "https://example.chorus.thirdlight.com/rest/v1/contexts/me" -H "X-Chorus-Session: TsVYymyYvhdz3wYPB-6D-6ARrtGvCG3o"
 
{
    "id": "me",
    "parentId": "dom0",
    "type": "PrivateSpace",
    "name": "Private",
    "avatarUrl": "https://cdn.example.chorus.thirdlight.com/avatar.tlx/H8uNg5vH8H8H3QPAH8T8LsT.png",
    "ownerId": "d36f04ba-8436-11e7-83cb-000c29aa9c88",
    "backingFolderId": "b5239a96-8438-11e7-bc10-000c29aa9c88"
}

gRPC Interface

The gRPC interface allows access to the API using an industry standard RPC framework. The suite of modules and methods available via gRPC is identical to that for the REST interface.

Third party support for a wide variety of languages is available, allowing developers to use their language of choice. If you are new to gRPC, the quick start guide is a good starting point. Please see: https://grpc.io/docs/quickstart/

The gRPC interface in Chorus is formally documented.

The methods available in the Chorus gRPC API are documented in /apidocs/grpc/ 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/grpc/.

gRPC Protocol Buffer Definitions

A set of protocol buffer definitions is available, which can be used to generate client bindings for languages supported by gRPC. The protocol buffers are documented under /apidocs/grpc/definitions/.

In gRPC, the gRPC server requires the session token to be provided as gRPC metadata, with a key of session.