OpenAPI Interface Documentation

This document describes how to call the OpenAPI interfaces provided by the platform, including authentication methods, signature algorithms, and interface examples.

Introduction to NineData OpenAPI

OpenAPI (Open Application Programming Interface) is a set of standardized interface specifications that allow developers to interact with external systems or services through programming. It is based on RESTful architectural design and provides standardized, lightweight, cross-platform data communication capabilities through the HTTP protocol, enabling rapid data interconnection and functional integration between different systems.

NineData's OpenAPI is a professional interface service for the field of data management, providing developers with a series of open application interfaces to manage NineData's data sources.

Request Header Parameters

Parameter Name	Required	Type	Description
access-key-id	Yes	string	The AccessKey ID issued by the platform (AccessKey), which can be viewed in the User Management section of the NineData Console after enabling AccessKey.
signature	Yes	string	Request signature for verifying the legality of the request. See the Generating Request Signature section of this document for details on how to obtain it.
timestamp	Yes	string	UTC timestamp in the format: `<yyyy-MM-dd>T<HH:mm:ss>Z` (example: 2024-05-31T09:15:33Z). See the Timestamp Specification section of this document for details on how to obtain it.
Content-type	POST required	string	Fixed to `application/json`, only required for POST requests.

Timestamp Specification

The timestamp is used for request header parameters and generating request signatures, and they must be completely consistent.

The format must strictly follow: <yyyy-MM-dd>T<HH:mm:ss>Z
Use UTC zero time zone (GMT+0) time
The server will check the difference between the timestamp and the server time, and requests exceeding 10 minutes will be rejected
Server time can be obtained through the interface:
curl http://<host>/openapi/now

Generating Request Signature

The generation of the request signature requires the following method to splice the interface address, SecretKey, and current timestamp, and calculate the signature through the sha256sum function.

In the NineData Console's User Management, click on Enable AccessKey under the Operations column to the right of the target user, and record the SecretKey.
Splice the message body according to the following method.
```
<Interface Address> + / + <SecretKey> + & + <Current Timestamp>
```
Example: /openapi/v1/region/list/Na12ssaaggffdd&2025-04-09T17:15:33Z
Calculate the SHA256 digest according to the following method to obtain the signature.
```
echo -n "<Spliced Message Body>" | sha256sum | awk '{print $1}'
```
Example: echo -n "/openapi/v1/region/list/Na12ssaaggffdd&2025-04-09T17:15:33Z" | sha256sum | awk '{print $1}'

Quick Integration Process

Notes

The timestamp must be completely consistent with the timestamp in the request header.
Windows users are recommended to use Git Bash to perform signature calculations.

Operation Process

Obtain Credentials: Log in to the NineData Console, enable AccessKey in User Management, and then record the AccessKey and SecretKey.
Obtain the current system timestamp.
Calculate the signature: Execute echo -n "/openapi/v1/region/list/<SecretKey>&<Current System Timestamp>" | sha256sum | awk '{print $1}' in the command line.
Make the official call: Splice the above information and send the interface call request. For example:
- GET request: curl http://console.ninedata.cloud/openapi/v1/region/list -H "access-key-id:<AccessKey>" -H "timestamp:<Current System Timestamp>" -H "signature:<Signature>"
- POST request: curl -H "access-key-id:<AccessKey>" -H "timestamp:<Current System Timestamp>" -H "signature:<Signature>" -H "Content-type:application/json" http://console.ninedata.cloud/openapi/v1/datasource/delete -d {"datasourceId":"<Data Source ID>"}

Interface Call Examples

This section provides example code for calling NineData OpenAPI.

Bash Example

#!/bin/bash

set -e

echo "current time : $(date)"

host=<IP>:<Port>

# Current timestamp
timestamp=$(date -u +%Y-%m-%dT%H:%M:%SZ)

accessKeyId="<accessKeyId>"
accessKeySecret="<accessKeySecret>"

echo "timestamp= $timestamp"
echo "accessKeyId= $accessKeyId"
echo "accessKeySecret= $accessKeySecret"

get()
{
  api=$1
  param=$2

  # Calculate signature
  signature=$(echo -n "$api/$accessKeySecret&$timestamp" \
    | sha256sum | awk '{print $1}')
  
  url="http://$host$api?$param"
  if [ -z "$param" ]; then
    url="http://$host$api"
  fi

  # GET request
  curl $url -H "access-key-id:$accessKeyId" -H "timestamp:$timestamp" -H "signature:$signature"
}

post()
{
  api=$1
  data=$2

  # Calculate signature
  signature=$(echo -n "$api/$accessKeySecret&$timestamp" \
    | sha256sum | awk '{print $1}')

  # POST request
  curl -H "access-key-id:$accessKeyId" \
         -H "timestamp:$timestamp" \
         -H "signature:$signature" \
         -H "Content-type:application/json" \
         http://$host$api \
         -d $data
}

get '/openapi/v1/region/list'

get '/openapi/v1/env/list' 'current=1&pageSize=10'

get '/openapi/v1/datasource/list' 'current=2&pageSize=10'

post '/openapi/v1/datasource/delete' '{"datasourceId":"<datasourceId>"}'

post '/openapi/v1/datasource/update' '{"datasourceId":"<datasourceId>","name":"Data Source"}'

post '/openapi/v1/datasource/create' '{"name":"Data Source","username":"root","host":"127.0.0.1","port":3306,"password":"123456","datasourceType":"MySQL","regionId":"cn-hangzhou","envId":"env-dev","networkType":"public"}'

Java Example

import java.io.*;
import java.net.*;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.time.Instant;
import java.time.ZoneId;
import java.time.format.DateTimeFormatter;

public class ApiClient {

    public static void main(String[] args) {
        String host = "<IP>:<Port>";
        String accessKeyId = "<accessKeyId>";
        String accessKeySecret = "<accessKeySecret>";

        // GET example
        sendGet(host, "/openapi/v1/region/list", "", accessKeyId, accessKeySecret);
        sendGet(host, "/openapi/v1/env/list", "current=1&pageSize=10", accessKeyId, accessKeySecret);
        sendGet(host, "/openapi/v1/datasource/list", "current=2&pageSize=10", accessKeyId, accessKeySecret);

        // POST example
        sendPost(host, "/openapi/v1/datasource/delete", 
                "{\"datasourceId\":\"<datasourceId>\"}", accessKeyId, accessKeySecret);
        
        sendPost(host, "/openapi/v1/datasource/update", 
                "{\"datasourceId\":\"<datasourceId>\",\"name\":\"Data Source\"}", accessKeyId, accessKeySecret);
        
        sendPost(host, "/openapi/v1/datasource/create", 
                "{\"name\":\"Data Source\",\"username\":\"root\",\"host\":\"127.0.0.1\"," +
                "\"port\":3306,\"password\":\"123456\",\"datasourceType\":\"MySQL\"," +
                "\"regionId\":\"cn-hangzhou\",\"envId\":\"env-dev\",\"networkType\":\"public\"}", 
                accessKeyId, accessKeySecret);
    }

    // Generate UTC timestamp
    private static String getTimestamp() {
        return DateTimeFormatter.ofPattern("yyyy-MM-dd'T'HH:mm:ss'Z'")
                .withZone(ZoneId.of("UTC"))
                .format(Instant.now());
    }

    // Generate signature
    private static String generateSignature(String api, String secret, String timestamp) 
            throws NoSuchAlgorithmException {
        String data = api + "/" + secret + "&" + timestamp;
        MessageDigest digest = MessageDigest.getInstance("SHA-256");
        byte[] hash = digest.digest(data.getBytes(StandardCharsets.UTF_8));
        
        StringBuilder hexString = new StringBuilder();
        for (byte b : hash) {
            String hex = String.format("%02x", b);
            hexString.append(hex);
        }
        return hexString.toString();
    }

    // GET request
    public static void sendGet(String host, String api, String params, 
                              String accessKeyId, String accessKeySecret) {
        try {
            String timestamp = getTimestamp();
            String signature = generateSignature(api, accessKeySecret, timestamp);
            
            URL url = new URL("http://" + host + api + (params.isEmpty() ? "" : "?" + params));
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();
            conn.setRequestMethod("GET");
            
            conn.setRequestProperty("access-key-id", accessKeyId);
            conn.setRequestProperty("timestamp", timestamp);
            conn.setRequestProperty("signature", signature);

            printResponse("GET", conn);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }

    // POST request
    public static void sendPost(String host, String api, String jsonBody,
                               String accessKeyId, String accessKeySecret) {
        try {
            String timestamp = getTimestamp();
            String signature = generateSignature(api, accessKeySecret, timestamp);
            
            URL url = new URL("http://" + host + api);
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();
            conn.setRequestMethod("POST");
            
            conn.setRequestProperty("access-key-id", accessKeyId);
            conn.setRequestProperty("timestamp", timestamp);
            conn.setRequestProperty("signature", signature);
            conn.setRequestProperty("Content-Type", "application/json");
            conn.setDoOutput(true);

            try (OutputStream os = conn.getOutputStream()) {
                byte[] input = jsonBody.getBytes(StandardCharsets.UTF_8);
                os.write(input, 0, input.length);
            }

            printResponse("POST", conn);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }

    // Print response information
    private static void printResponse(String method, HttpURLConnection conn) throws IOException {
        int status = conn.getResponseCode();
        StringBuilder response = new StringBuilder();
        
        try (BufferedReader br = new BufferedReader(
            new InputStreamReader(status >= 400 ? conn.getErrorStream() : conn.getInputStream()))) {
            
            String line;
            while ((line = br.readLine()) != null) {
                response.append(line);
            }
        }
        
        System.out.printf("\n--- %s Response [%d] ---\n%s\n", 
                         method, status, response.toString());
    }
}

OpenAPI Interface Documentation

Introduction to NineData OpenAPI​

Request Header Parameters​

Timestamp Specification​

Generating Request Signature​

Quick Integration Process​

Interface Call Examples​