Developer's guide¶

Authenticate with API key¶

The Chemaxon Calculators and Predictors service is secured from unauthorized use by allowing only those API calls that provide proper authentication credentials. These credentials are in the form of an API key - a unique alphanumeric string associated to your AWS account.

Getting the API key¶

Once you subscribe to the Calculators and Predictors service on AWS Marketplace, you will be redirected to our welcome page where you can redeem your API key.

 {primary} Save the key and store it in a safe place. This is the only time we will show you the API key.

Once you close or refresh the window, you won't be able to recover the API key.
You will be charged for every API call that uses this key. Make sure you are the only one who has access to it.
Your API key will be activated once AWS fully processes your subscription. This typically takes a few seconds, but in rare cases it can take up to 30 minutes.

Using the API key¶

To gain access to our services, you must add the x-api-key header to all of your requests. The value of the header can only be the API key and nothing else:

1	`x-api-key: <YOUR_API_KEY>`

For detailed examples check the Code examples section.

Revoking the API key¶

To revoke your API key, you have to unsubscribe from our services on the AWS Marketplace product page. This action triggers mechanisms in the background that revoke your API key immediately.

Re-generate the API key¶

We don't provide this functionality as is, but you can unsubscribe from using Chemaxon Calculators and Predictors on AWS Marketplace product page and subscribe again. This has the effect of revoking your current API key and getting a new one.

Subscribing and unsubscribing to the service is free of charge. We only charge you for the API calls you make.

Check API key validity¶

You can check any time if your API key is still valid at marketplace.calculators.cxn.io. In case of a valid API key we provide additional information, e.g. the pricing plan you chose. For more information, see Pricing.

API Limitations¶

Maximum execution time¶

Each request is allowed to run for a maximum of 25 seconds. After that time period your request calls a timeout and returns with HTTP status code 504 Gateway Timeout.

Rate limit¶

A rate limit is the number of API calls a user can make within a given time period.
Our system limits API calls to 50 request/sec. Please note that this is not hard limit but rather applied on a best-effort basis. In some cases you can exceed the rate that you set.

Maximum number of structures within a batch call¶

Calculators and Predictors on AWS Marketplace provides an API (/rest-v1/calculator/batch/calculate) that allows calculations for multiple structures within a single call.
The maximum number of structures is limited to 25 structures.

API documentation¶

A temporary API documentation can be found at this swagger page.

AWS PrivateLink¶

What is AWS PrivateLink?

AWS PrivateLink is a highly available, scalable technology that enables you to privately connect your VPC to services as if they were in your VPC. Therefore, you control the specific API endpoints, sites and services that are reachable from your VPC.

Available AWS regions and their endpoint service names for PrivateLink connection:

eu-west-1: com.amazonaws.vpce.eu-west-1.vpce-svc-0de31eeb3a6603741
us-east-2: com.amazonaws.vpce.us-east-2.vpce-svc-0227bb48a9c19e263

How to connect to Chemaxon Calculators and Predictors using the PrivateLink option?

AWS Console:

Amazon provides a great step-by-step documentation on how to access SaaS products through AWS PrivateLink. Please follow the steps described here and use the region's service name specified above.
Enable the Private DNS name option on the created endpoint.
The service can be accessed using the private-api.calculators.cxn.io address from the specified VPC.

AWS CLI:

aws ec2 create-vpc-endpoint \
   --vpc-id <vpc-id> \
   --subnet-ids <subnet-id> \
   --service-name com.amazonaws.vpce.eu-west-1.vpce-svc-0de31eeb3a6603741 \
   --private-dns-enabled

Is it possible to use the service via PrivateLink from a VPC that is located outside of the available regions (e.g. us-west-1)?

Yes, it is possible with the following steps:

Create a VPC in any supported region, e.g. us-east-2.
Connect to our service via PrivateLink from this VPC.
Create an inter-region VPC peering connection between your VPCs (us-east-2 vs us-west-1).

Code examples¶

The following section provides code examples in different languages on how to use a basic calculator (Elemental Analysis) by authenticating the request using the API key.

curl¶

curl -X 'POST' \
  'https://api.calculators.cxn.io/rest-v1/calculator/calculate/elemental-analysis' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
  "structure": "NC(CC1=CC=CC=C1)C(O)=O"
}'

Javascript¶

const url = 'https://api.calculators.cxn.io/rest-v1/calculator/calculate/elemental-analysis';
const payload = {
  structure: 'NC(CC1=CC=CC=C1)C(O)=O'
};

const response = await fetch(url, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'YOUR_API_KEY',
  },
  body: JSON.stringify(payload)
});

Python¶

import requests

url = 'https://api.calculators.cxn.io/rest-v1/calculator/calculate/elemental-analysis'
payload = { 'structure': 'NC(CC1=CC=CC=C1)C(O)=O' }
my_headers = {
  'x-api-key': 'YOUR_API_KEY',
  'Content-Type': 'application/json'
}

response = requests.post(url, json=payload, headers=my_headers)

Java¶

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpRequest.BodyPublishers;
import java.net.http.HttpResponse;
import java.net.http.HttpResponse.BodyHandlers;
import java.time.Duration;

import com.google.gson.Gson;

public class App {
  public static void main(String[] args) {
    // This code requires Java 11 or newer
    var request = HttpRequest.newBuilder()
      .uri(URI.create("https://api.calculators.cxn.io/rest-v1/calculator/calculate/elemental-analysis"))
      .header("x-api-key", "YOUR_API_KEY")
      .header("Content-Type", "application/json")
      .POST(BodyPublishers.ofString("{ \"structure\": \"NC(CC1=CC=CC=C1)C(O)=O\" }"))
      .timeout(Duration.ofSeconds(5))
      .build();

    var responseStr = HttpClient.newHttpClient()
      .sendAsync(request, BodyHandlers.ofString())
      .thenApply(HttpResponse::body)
      .join();

    // Multiple libraries are available to parse the JSON response, e.g., gson (https://github.com/google/gson)
    var response = new Gson().fromJson(responseStr, Response.class);
  }

  static class Response {
    private double mass;
    private double exactMass;
    private String formula;

    // ... other fields
    // ... getters, setters
  }
}

How to achieve the best performance¶

Coming soon...

FAQ¶

What if I lost my API key?¶

In case you need a new API key, you have to unsubscribe from this product on AWS Marketplace page and subscribe again. This process removes your previous API key associated to your account and assign a new one.

Can I own multiple API keys?¶

No, you can only have one API key associated to your AWS account.

Does subscribing to Chemaxon Calculators and Predictors cost any money?¶

Subscribing and unsubscribing to the service is free of charge. We only charge you for the API calls you make.

How much does an API call cost?¶

Each chemical calculation API call has a different price based on how complex the calculation is. For the detailed list, see Pricing.

Where can I get information about the status of the service?¶

The status page, integrated with out monitoring and alerting system, provides up-to-date information on the incidents, system status and planned maintenance.