CIRCUS API Introduction

All of the functions of CIRCUS CS/DB can be accessed via RESTful API.

API Endpoint

All of the API endpoints are prefixed with /api.

Authentication

First, you need a permanent access token to access the API. It can be obtained in two ways.

• The first option: Log in to CIRCUS Web UI and go to the "Access Tokens" section under the Tool menu.

• The second option: Use CIRCUS CLI. Attach to the CIRCUS Docker container and issue the following command.

  $ node circus add-permanent-token <user-email>

Keep the Token Secret!

Your permanent access tokens will remain valid even after you have logged out of the CIRCUS web UI, and it can do anything on behalf of your account.

Save the generated token somewhere securely. You cannot see it from the system again.

You can use the token in the Authorization header in an API request, like so:

Authorization: Bearer 5ccec1795806a75fd3ea6800e99ade60ddda76bb

Any programming language or command that is capable of making HTTP requests can be used to access the API.

Basic Examples

The following examples access /api/series endpoint to search DICOM series uploaded to the system.

Before trying the following samples, you need a permanent access token.

JavaScript

index.js

// This example uses 'node-fetch', but you can use any HTTP library.
// Other popular options include axios and superagent.
const fetch = require('node-fetch');

// Replace these according to your environment.
const token = '5ccec1795806a75fd3ea6800e99ade60ddda76bb';
const server = 'localhost:8080';

const main = async () => {
  const res = await fetch(`http://${server}/api/series`, {
    headers: {
      Authorization: `Bearer ${token}`,
    },
  });
  const data = await res.json();
  console.log(data);
};

main();

Python

index.py

# This example uses 'Requests', but you can use any HTTP library.
import requests

def main(token, server):
    url = 'http://{}/api/series'.format(server)
    headers = { 'Authorization': 'Bearer {}'.format(token)}
    return requests.get(url, headers=headers).json()

if __name__ == '__main__':

    token = '5ccec1795806a75fd3ea6800e99ade60ddda76bb'
    server = 'localhost:8080'

    data = main(token, server)
    print(data)

cURL (bash)

curl.bash

#!/usr/bin/bash

# Replace these according to your environment.
TOKEN=5ccec1795806a75fd3ea6800e99ade60ddda76bb
SERVER=localhost:8080

curl -H "Authorization: Bearer ${TOKEN}" \
  http://${SERVER}/api/series

You can also use convenient apps such as VSCode's REST Client extension.

Form Your Request

Requests are JSON-based (MIME: application/json) with a few exceptions. When you POST or PUT something to API, you must add the Content-Type: application/json header, but may HTTP clients handle this automatically. All JSON requests and responses are UTF-8 encoded.

The server may return a 2xx status code for successful requests.

• 200 OK: For most GET requests
• 201 Created: For most PUT/POST requests
• 204 No Content: For most DELETE/PATCH requests and some other requests that return no response body

The server may return a 4xx status code for unprocessable requests.

• 400 Bad Request: For most client-side errors such as malformed JSON or wrong request body.
• 401 Unauthorized: For requests that has no access token in the header, and requests from users with insufficient privileges.