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 5ccec1795806a75fd3ea6800e99ade60ddda76bbAny 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.
// 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();# 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)#!/usr/bin/bash
# Replace these according to your environment.
TOKEN=5ccec1795806a75fd3ea6800e99ade60ddda76bb
SERVER=localhost:8080
curl -H "Authorization: Bearer ${TOKEN}" \
http://${SERVER}/api/seriesYou 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.