Design Hub developer guide - REST API

• Authorize requests
  • with API key
  • with Bearer token
  • Error codes
• Methods
  • GET /api/user
  • GET /api/projects
  • GET /api/hypotheses
  • GET /api/designsets
  • GET /api/compounds/public
  • POST /api/compounds/:id/data
  • POST /api/compounds/:id/additionalfield
  • POST /api/compounds/:id/attach
  • POST /api/compounds/internal/:id/attach
  • GET /api/compounds/export
  • POST /api/tags/:id
  • POST /upload/api - multipart
  • POST /upload/api - JSON

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. Additionally, when using OpenIDConnect authentication, Bearer tokens issued by the identity provider can be used as well.

Authorize requests with API key

Use of most API endpoints requires a successful token based authentication. The user needs ACCESS_REST_API permission to be able to manipulate and view API tokens. 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.

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"
}

Authorize requests with Bearer tokens

Use of most API endpoints requires a successful authentication. Using OpenIDConnect based authentication, users with valid access tokens can authorize requests using Bearer authentication. The token can be obtained from the identity provider.

Once a token is available, specifying them on HTTP requests can be done on the Authorization header:

user:~/app$ export TOKEN=eyJhbG...FaEyTA
user:~/app$ curl -H "Authorization: Bearer $TOKEN" "http://server:port/api/domainname/user"
{
  "user_id": 1,
  "displayName": "Tester"
}

Error codes

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 or Authorization header not specified on the request
401 Unauthorized	X-API-KEY value or Bearer token is invalid
404 Not found	HTTP path or method specified in the request doesn't exist

Methods

Get user details

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

Get projects

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.

Get hypotheses

HTTP Request: GET /api/hypotheses

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

Request headers: X-API-KEY required

Response content-type: application/json

Query parameters:

Parameter name	type	Description
myprojects	boolean (optional)	Filter by projects to which the user is assigned
project_id	list of numbers	Filter by a comma separated list of project identifiers to which the hypotheses belong

Response body:

[
  {
    "content_id": string,
    "title": string,
    "tags": string,
    "create_date": string,
    "modify_date": string,
    "project_id": number
  }, ...
}

Property name	Value	Description
hypothesis list	list	An unordered list of hypotheses.
hypothesis list[*].content_id	string	Unique, internal identifier of the hypothesis.
hypothesis list[*].title	string	Human friendly name of the hypothesis.
hypothesis list[*].tags	List of string	A list of tags assigned to the hypothesis.
hypothesis list[*].create_date	string	The date when the hypothesis was created, in ISO date format, UTC timezone.
hypothesis list[*].modify_date	string	The date when the hypothesis was last changed, in ISO date format, UTC timezone.
hypothesis list[*].project_id	number	The unique identifier of the project.

Get design sets

HTTP Request: GET /api/designsets

Purpose: Provides list of design sets accessible to the authorized user.

Request headers: X-API-KEY required

Response content-type: application/json

Query parameters:

Parameter name	type	Description
project_id	list of numbers	Filter by a comma separated list of project identifiers to which the design sets belong

Response body:

[
  {
    "content_id": string,
    "parent_id": string,
    "title": string,
    "tags": string,
    "create_date": string,
    "modify_date": string,
    "parent_title": string,
    "parent_content_id": string
  }, ...
}

Property name	Value	Description
design set list	list	An unordered list of design sets.
design set list[*].content_id	string	Unique, internal identifier of the design set.
design set list[*].title	string	Human friendly name of the design set.
design set list[*].tags	List of string	A list of tags assigned to the design set.
design set list[*].create_date	string	The date when the design set was created, in ISO date format, UTC timezone.
design set list[*].modify_date	string	The date when the design set was last changed, in ISO date format, UTC timezone.
design set list[*].parent_title	string	The design set's parent title.
design set list[*].parent_content_id	string	The design set's parent unique, internal identifier.

List compounds and IDs

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

Query parameters:

Parameter name	type	Description
offset	number (optional)	number of compounds to skip in the beginning of the list, default 0
limit	number (optional)	maximum size of list, default based on Design Hub config parameter limitPublicCompoundsListSize
format	string (optional)	output compound format supported by JChem IO Web Service

Response body:

{
  "compounds": [
    {
      "currentId": string,
      "previousIds": [ string, ... ],
      "source": string,
      "url": string
    },
    ...
  ],
  "total": number,
  "limit": number,
  "offset": number
}

Property name	Value	Description
compounds	list	A list of compound records ordered by record creation date
compounds[*].currentId	string	Latest known ID of the compound, e.g. "CXN-123456"
compounds[*].previousIds	list of strings	List of previously known IDs of the compound, e.g.: ["VXN-1234567"]
compounds[*].source	string	formatted source of the compound (formatted by provided format, MRV if format not provided)
compounds[*].url	string	A root relative URL to the compound's dedicated webpage, e.g.: "/compounds/find/CXN-123456"
compounds[*].formattedSourceError	string	Error detail if compound cannot be converted to specified format.
total	number	Number of all public compounds that can be obtained using this endpoint
offset	number	Index of the first compound in this result set
limit	number	Number of compounds requested

Upload data to compound

HTTP Request: POST /api/compounds/:id/data

Purpose: adds uploaded data to a compound

Request headers : X-API-KEY required

URL parameters:

Parameter name	type	Description
id	string	the content ID, virtual ID or substance ID of the selected compound

Request parameters:

Parameter name	type	Description
column	string	Column name for the uploaded value
value	string or number	Uploaded value

Response: Http status 200 in case of success, error code otherwise

Upload additional field value to compound

HTTP Request: POST /api/compounds/:id/additionalfield

Purpose: uploads value of given additional field to a compound

Request headers : X-API-KEY required

URL parameters:

Parameter name	type	Description
id	string	the content ID, virtual ID or substance ID of the selected compound

Request parameters:

Parameter name	type	Description
name	string	Name of the additional field (not label)
value	string or number	New value of the field

Response: Http status 200 in case of success, error code otherwise

Attach data to compound

HTTP Request: POST /api/compounds/:id/attach

Purpose: allows attaching generated files, and comments to a compound

Request headers : X-API-KEY required

Response content-type: application/json

URL parameters:

Parameter name	type	Description
id	string	the content ID of the selected compound

Request parameters:

Parameter name	type	Description
link	string	A single URL (https://) to be attached to the compound as a comment
comment	string	A free text comment to be added to the compound
files	array of objects	A list of generated files to attach to the compound
files[*].fileName	string	name of the file
files[*].content	string	plain text contents of the file for text or xml files
files[*].contentBase64	string	base64 encoded contents of the file for binary files
files[*].mimeType	string	mime type hint for the file - for certain mime types thumbnail images may be generated
visibility	string	the visibility type of the attachement. One of internal or public. Default: public.

Response body:

{
  "contentUrl": string
}

Attach internal data to compound

HTTP Request: POST /api/compounds/internal/:id/attach

Same as Attach internal data to compound used with the visibility parameter set to internal.

Deprecated in favor of Attach internal data to compound.

Export compounds data

HTTP Request: GET /api/compounds/export

Purpose: allows the export of compounds data using filters

Request headers : X-API-KEY required

Response content-type: application/json

Query parameters:

Parameter name	type	Description
offset	number	number of compounds to skip in the beginning of the list, default 0
limit	number	maximum size of list, default based on Design Hub config parameter limitPublicCompoundsListSize
format	string (optional)	output compound format supported by JChem IO Web Service
registration_ids	string	a comma separated list of latest known ID of the compounds
project_label	string	a project label
hypothesis_content_ids	string	comma separated list of hypotheses identifiers
hypothesis	string	comma separated hypothesis titles
designset_content_ids	string	a comma separated list of design set identifiers
designset	string	comma separate list of design set titles
status	string	comma separated list of compound statuses; e.g. Draft, Ready for review, ...
author	string	comma separated list of display names of compound authors
assignee	string	comma separated list of display names for compound assignees
structure	string	chemical query structure in SMARTS or CXSMARTS format
searchType	string	chemical search type. One of sss, sim, or dup. Default: sub.
create_date	string	a relative date filter to show compounds that were created within the desired time frame; accepted values are from this set: [1d, 1w, 1m, 3m, 1y, 10y]
create_date_before	Date in ISO8601 format in UTC	the creation date of the compound has to be before this date. If a value for create_date is given, this parameter will be ignored.
create_date_after	Date in ISO8601 format in UTC	the creation date of the compound has to be after this date. If a value for create_date is given, this parameter will be ignored.
modify_date	string	a relative date filter to show compounds that were modified within the desired time frame; accepted values are from this set: [1d, 1w, 1m, 3m, 1y, 10y]
modify_date_before	Date in ISO8601 format in UTC	the last modification date of the compound has to be before this date. If a value for modify_date is given, this parameter will be ignored.
modify_date_after	Date in ISO8601 format in UTC	the last modification date has to be after this date. If a value for modify_date is given, this parameter will be ignored.
visibility	string	tharing related state of a compound. One of: private, public or mixed. Default: mixed.

Response body:

{
  "compounds": [
    {
      "id": string,
      "private": boolean,
      "project_label": string,
      "project_key": string,
      "designset": string,
      "hypothesis": string,
      "author": string,
      "assignee": string,
      "create_date": string,
      "modify_date": string,
      <calculated data fields>
    },
    ...
  ],
  "total": number,
  "limit": number,
  "offset": number,
  "hasMore": boolean
}

Property name	Value	Description
compounds	list	A list of compound records ordered by record creation date.
compounds[*].id	string	Latest known ID of the compound, e.g. "CXN-123456".
compounds[*].private	boolean	Visibility of the compound.
compounds[*].project_label	string	The project to which this compound belongs.
compounds[*].project_key	string	The project identifier to which the compound belongs.
compounds[*].designset_title	string	The design set title to which the compound belongs.
compounds[*].designset_content_id	string	The design set identifier to which the compound belongs.
compounds[*].hypothesis_title	string	The hypothesis title to which the compound belongs.
compounds[*].hypothesis_content_id	string	The hypothesis identifier to which the compound belongs.
compounds[*].author	string	The username of the compound's author.
compounds[*].assignee	string	The username of the user to which the compound is assigned.
compounds[*].create_date	string	The date when the compund was created, in ISO date format, UTC timezone.
compounds[*].modify_date	string	The date when the compund was last changed, in ISO date format, UTC timezone.
compounds[*].source	string	formatted source of the compound (formatted by provided format, MRV if format not provided).
compounds[*].<calculated data fields>	string|number|boolean	Additional fields containing calculated date for the compound.
compounds[*].formattedSourceError	string	Error detail if compound cannot be converted to specified format.
total	number	Number of all public compounds that can be obtained using this endpoint.
offset	number	Index of the first compound in this result set.
limit	number	Number of compounds requested.
hasMore	boolean	Indicates that there are more compunds matching the specified filters.

Upload tags to compound, designset or hypothesis

HTTP Request: POST /api/tags/:id

Purpose: uploads tags to a compound, designset or hypothesis

Request headers : X-API-KEY required

URL parameters:

Parameter name	type	Description
id	string	the content ID, virtual ID or substance ID of a compound or content ID of a designset or content ID of a hypothesis

Request parameters:

Parameter name	type	Description
command	string	Either Add or ReplaceAll. Add adds the list of tags to the existing tags, ReplaceAll removes all existing tags and replace them with the provided array
tags	array of strings	Tags to be added (ReplaceAll with empty array removes the existing tags)

Response: Http status 200 in case of success, error code otherwise

Multipart form upload

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 structures=@/path/to/file/filename.sdf "http://localhost:8888/upload/api"

A browser form with a file input 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

JSON upload

HTTP Request: POST /upload/api

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/api 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"
}