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>

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.

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();

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.