Design Hub developer guide - REST API

  • GET /api/user

  • GET /api/projects

  • GET /api/compounds/public

  • POST /upload/api

  • POST /upload/json

REST API

Available from v20.13.0, Design Hub includes a token based API access layer. Authenticated users of the system can generate API keys to be used to authorize HTTP requests made by other applications, outside of active login sessions.

Authorize requests

Use of most API endpoints requires a successful token based authentication. When API access is enabled in the application, the token can be obtained by opening the corner menu on the user interface and creating a new token. Here, previous tokens can be invalidated as well.

images/download/attachments/17272767/Screenshot_2020-03-05_at_22.28.44.png

Once a token has been obtained, specifying them on HTTP requests can be done in the X-API-KEY header:

user:~/app$ curl -H "X-API-KEY: XFBg+9IVHhTRviLF1WOHgD0U2QS5Ww8oHqqG+405" http://server:port/api/user
{
"user_id": 1,
"displayName": "Tester"
}

Different HTTP errors are returned for incorrect authentication. The following spreadsheets describes which status code corresponds to which check.

Status code

Description

400 Bad request

X-API-KEY header not specified on the request

401 Unauthorized

X-API-KEY value is invalid

404 Not found

HTTP path or method specified in the request doesn't exist

Methods

HTTP Request: GET /api/user

Purpose: Provides basic information about the user authorized by the access token.

Request headers: X-API-KEY required

Response content-type: application/json

Response body:

{
"user_id": number,
"displayName": string
}

Property name

Value

Description

user_id

number

internal identifier of the user

displayName

string

user-specified display name

HTTP Request: GET /api/projects

Purpose: Provides list of projects accessible to the authorized user.

Request headers: X-API-KEY required

Response content-type: application/json

Response body:

[
{
"project_id": number,
"label": string,
"last_used": string
}, ...
}

Property name

Value

Description

project list

list

An unordered list of projects

project list[*].project_id

number

Unique, internal identifier of the project.

project list[*].label

string

Human friendly name of the project.

project list[*].last_used

string

Serialized date object representing when this project was last used, in ISO date format, UTC timezone. May be used for sorting.

HTTP Request: GET /api/compounds/public

Purpose: Provides all IDs and compounds publicly available in the system. May be used to make Design Hub generated IDs usable in other systems.

Request headers: X-API-KEY required

Response content-type: application/json

Response body:

[
{
"currentId": string,
"previousIds": [ string, ... ],
"source": string
}, ...
}

Property name

Value

Description

compound list

list

An unordered list of compounds

compound list[*].currentId

string

Latest known ID of the compound, e.g. "CXN-123456"

compound list[*].previousIds

list of strings

List of previously known IDs of the compound, e.g.: ["VXN-1234567"]

compound list[*].source

string

MRV formatted source of the compound

HTTP Request: POST /upload/api

Purpose: Provides a way for simple web sites to send molecules to Design Hub.

Request content-type: multipart/form-data

Request body: a chemical structure file recognized by ChemAxon IO system

Response content-type: application/json

Response body: a HTTP redirect that should be opened by the user's browser

Example:

A curl command produces valid multipart request, when the data flag refers to a file using the @ symbol:

user:~/app$ curl -X POST -F [email protected]/path/to/file/filename.sdf "http://localhost:8888/upload/api"

A browser file upload form also produces a valid multipart request, when the form ’s action attribute and the file input ’s name attribute are specified as below:

<form action="http://design-hub-example.com/upload/api" enctype="multipart/form-data" method="post">
 <input type="file" name="structures" />
 <button>Upload</button>
</form>

When submitted, this sends the following HTTP request:

POST /upload/api HTTP/1.1
Host: design-hub-example.com
Content-Type: multipart/form-data; boundary="the_boundary"
Content-Length: number_of_bytes_in_entire_request_body
--the_boundary
Content-Disposition: form-data; name="structures"; filename="records.mrv"
Content-Type: application/octet-stream
 
Chemical file data
--the_boundary--

If the request succeeds, the server returns HTTP 302 Moved temporarily status code, along with a redirect URL containing a unique ID that references the parsed contents of the file. Integrating applications should open this URL in the user’s browser. This unique URL is valid for 5 minutes.

HTTP/1.1 302
Location: /new/compound/?cache=1164293e37ca9d47cbdfded5

HTTP Request: POST /upload/json

Purpose: Provides a way for applications to send molecules to Design Hub.

Request content-type: application/json

Request body:

Property name

Value

Description

structures

string

A string serialized representation of a chemical structure file recognized by ChemAxon IO system

Response content-type: application/json

Response body: a JSON object including the following properties:

Property name

Value

Description

url

string

a root relative URL (path) that should be opened by the user's browser

Example:

A valid request has the Content-Type of application/json and the body contains a JSON structure, with the file contents under the structures key:

POST /upload/json HTTP/1.1
Host: design-hub-example.com
Content-Type: application/json
Content-Length: number_of_bytes_in_entire_request_body
{ "structures": "chemical file data" }

If the request succeeds, the server returns a simple JSON object containing a unique URL that references the parsed contents of the file. Integrating applications should open this URL in the user’s browser. This unique URL is valid for 5 minutes.

HTTP/1.1 200
{
"url": "/new/compound/?cache=1164293e37ca9d47cbdfded5"
}