To use the API endpoints, you need to access and activate the 3decision API. For this, the required steps are:
- Generate an API Secret Key - to generate an access token.
- Generate an access token - to provide the necessary authorizations (endpoint
GET /auth/api/login). - Authorize the use of the 3decision API - to call 3decision API endpoints.
Instructions on how to perform all these steps are documented in the following sections. Instructions from the 3decision API interface, Curl commands, and Python scripts are reported.
¶ 1. Generate an API Secret Key
API Secret Keys are managed from the user interface.
- Log in to 3decision via the user interface. (e.g.
https://3decision<customer>.discngine.cloud) - Click on the “My Profile” icon (bottom left)
- Select “API”
- Click on “New API Secret Key”
- Give a name and select an expiration date then click on “Create”
The API Secret Key by default has a validity of 1 Day.
- Copy the generated API secret key by clicking on the copy icon. Be careful to save the API secret key somewhere safe, as you will not be able to display it again once the tab is closed. For some security reason, the API secret key generated for this documentation is hidden under the grey rectangle.
¶ 2. Generate a token
To generate a valid token, you must authenticate yourself using a valid API Secret Key (described in the section above “Generate an API Secret Key”).
The generated token by default has an expiration time of 1 hour.
Several ways of generating a valid token are described below.
¶ From the 3decision API interface:
- Go to the 3decision API. You can do that using the direct link in the format:
https://3decision-<customer>-api.discngine.cloud/full/(NB: this link is unique for each customer).
Alternatively, a link to the 3decision API can be found under the API menu in the user interface:
- Open the
GET /auth/api/loginendpoint - Click on “Try it out” to activate the endpoint
- Paste a valid API Secret Key in the
Dng-Api-Keyfield.
- Click on "Execute"(blue button at the bottom)
- The token is generated and appears in the Response body under “Server response"
- Copy and save the Token (only the value in green between the quotation marks)
¶ Using the ‘curl’ command:
The request must be sent to the ‘/auth/api/login’ route (i.e. https://3decision<customer>-api.discngine.cloud/full/api/login ). Specify a header called ‘Dng-Api-Key‘ with the generated API Secret Key as the value.
curl -X 'GET' \
'https://3decision-<customer>-api.discngine.cloud/auth/api/login' \
-H 'accept: application/json' \
-H 'X-API-VERSION: 1' \
-H 'Dng-Api-Key: XXXXXXXXXXXXXXXXXXXX
¶ Using Python:
You can use a Python script to generate the token from the API secret key. You need to import ‘json’ and ‘requests’ libraries.
import json
import requests
Then we define a function get_token() to generate it.
def get_token(
login_endpoint: str, headers: dict[str, str], refresh: bool = False
) -> str:
"""Generate a new token from the API secret, or refresh the current one.
Parameters
----------
refresh : bool, optional
if refresh is set to True, the token will be regenerated, by default False
Returns
----------
str
The user token.
"""
def _login(endpoint: str) -> str:
response = requests.get(
endpoint,
headers=headers,
)
return response.json()["access_token"]
if not hasattr(get_token, "token") or refresh:
# Generate a new token if we don't have one, or if we want to refresh it
setattr(get_token, "token", _login(login_endpoint))
# Else, use the token already generated
return getattr(get_token, "token")
You can call it in a main
def main():
"""Call 3decision API."""
api_secret_key: str = "XXXXXXXXXX"
api_url: str = "https://3decision-<customer>-api.discngine.cloud"
login_endpoint: str = f"{api_url}/auth/api/login"
headers: dict[str, str] = {
"Dng-Api-Key": api_secret_key,
"Content-Type": "application/json",
"X-API-VERSION": "1",
}
# Setup request headers, with authentication token
token: str = get_token(login_endpoint, headers)
if __name__ == "__main__":
main()
¶ 3. Authorize the use of the 3decision API
To call 3decision API endpoints, you must have the authorization provided by the token (generated in the section above “Generate a token”).
The token must be added as an OAuth 2.0 token (i.e. the header ‘Authorization’ set to ‘Bearer token_value’). If a request is incorrectly authenticated or the token has expired, a response with a 401 status code (Unauthorized) will be returned.
Generated tokens expire after one hour, regardless of the expiration date of the DNG API Key.
Several ways of calling the 3decision API are described below.
¶ Using the 3decision API interface:
-
From the API (
https://3decision-<customer>-api.discngine.cloud/full), click on "Authorize" on the top right of the page
-
Paste your Token (only the token value, without the quotation marks)
- Click on "Authorize” (any string will return "Authorized", but only the correct token allows you to run endpoints)
- Close the “Available authorizations” tab
Now you can call all endpoints of the 3decision API
¶ Using the 'curl' command:
Each endpoint of the 3decision API can be called using dedicated routes. An example is the /projects endpoint (that returns all accessible projects for the user linked to this token). An example of ‘curl’ command is:
#!/usr/bin/env bash
TOKEN=XXXXXXXXXX
curl -X 'POST' \
'https://3decision-<customer>-api.discngine.cloud/projects' \
-H 'accept: application/json' \
-H 'X-API-VERSION: 1' \
-H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"has_auto_superposition": true,
"description": "My project description",
"label": "My unique project label",
"projectTypeCode": "GEN"
}'
¶ Using Python:
You can add a call to the 3decision API in the main, after the generation of the token.
def main():
"""Call 3decision API."""
api_secret_key: str = "XXXXXXXXXX"
api_url: str = "https://3decision-<customer>-api.discngine.cloud"
login_endpoint: str = f"{api_url}/auth/api/login"
headers: dict[str, str] = {
"Dng-Api-Key": api_secret_key,
"Content-Type": "application/json",
"X-API-VERSION": "1",
}
# Setup request headers, with authentication token
token: str = get_token(login_endpoint, headers)
# Endpoint you'd like to use
endpoint: str = f"{api_url}/projects"
# Payload to send
payload = {
"has_auto_superposition": True,
"description": "My project description",
"label": "My unique label 2",
"projectTypeCode": "GEN",
}
headers: dict[str, str] = {
"Content-Type": "application/json",
"accept": "application/json",
"Authorization": f"Bearer {token}",
"X-API-VERSION": "1",
}
# Make request
response: requests.Response = requests.post(
endpoint,
headers=headers,
data=json.dumps(payload),
)
if response.status_code < 400:
print("Everything went fine, response:")
else:
print("Creation failed, response:")
print(json.dumps(response.json(), indent=True))
¶ Asynchronous job
Several API endpoints are asynchronous, they send the request as a job and return results later.
It avoids to wait for the response of a long time job while it runs.
An example of asynchronous endpoint is the POST /structure-registration endpoint.
When it is called, it returns a job ID (identifier) which can be used to retrieve the results (see "Structure Registration" for more details).
For some endpoints, there is an optional property called async - short for
asynchronous.
- If
asyncis set toTrue, the response is a queue name and a job ID (where the job is running) - If
asyncis set toFalse, the response is directly returned in the response body
When a job is run asynchronously, you can retrieve the results by using the endpoint GET /queues/{queue}/jobs/{job_id}:
- Fill the values of
{queue}and{job_id}by the queue name and the job ID returned when posting the job asynchronously.
¶ Example with asynchronous job on /search/chemistry
We post a search to perform on the molecule “ N1C=CC=C1” with a similarity of 0.65 with the similarity search method.
We get this results :
The property "id" in the response will let you to fill the {job_id} value, and the "queue" property for {queue}.
¶ Retrieve data from asynchronous job
To retrieve a result from an asynchronous job, we use this endpoint GET /queues/{queue}/jobs/{job_id}
For our example, we have:
After clicking on Execute, we directly get the results of the search under the "returnvalue" property in the response:
¶ Example with synchronous job on /search/chemistry
You have to set the property "async" to false if you want a synchronous job.
And then you directly get the response.
