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 ConsoleNineData 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 ConsoleNineData 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());
    }
}

Interface List

Public Interfaces

Get server time: GET /openapi/now

Data Source Management Interfaces

Interface Name	Interface Description
Create Data Source	Create a new database connection configuration in NineData.
Delete Data Source	Delete the target data source from NineData.
Update Data Source	Update the connection information of the data source already entered in NineData. You can modify the name, account, password, connection address, port, and environment of the data source, etc.
Get Data Source List	Paged query of data source list, support filtering by data source ID, data source name, data source type.
Query Environment Information	Get the list of all available environments in NineData, support filtering by environment name.
Query Region Information	Get the list of all available regions in NineData.

Account Management APIs

API Name	Description
Get Account List	Paginated query of the NineData account list, supporting filtering by account ID, account name, and login name.

Role Management APIs

API Name	Description
List Roles	Paginated query of the role list under the current organization.
Create Role	Creates a new custom role.
List Role Members	Queries the member list under a specified role.
Update Role Name	Updates the name of a specified role.
Update Role Module Permissions	Updates the module permission configuration of a specified role.
Delete Role	Deletes a specified role.
Add Role Members	Adds one or more members to a specified role.
Delete Role Member	Deletes a member from a specified role.
List Role Module Permissions	Queries the module permission list of a specified role.

Rule Set APIs

API Name	Description
List Rule Sets	Paginated query of rule sets in the current organization.
Create Rule Set	Copies an existing rule set and creates a new rule set.
Delete Rule Set	Deletes a specified rule set.
Bind or Unbind Rule Set Resources	Binds a rule set to specified resources or removes the binding from specified resources.

Approval Group APIs

API Name	Description
List Approval Groups	Paginated query of approval groups in the current organization.
Create Approval Group	Copies an existing approval group and creates a new approval group.
Delete Approval Group	Deletes a specified approval group.
Update Approval Group	Updates the name, description, and approval settings of a specified approval group.
Bind or Unbind Approval Group Resources	Binds an approval group to specified resources or removes the binding from specified resources.

Permission APIs

API Name	Description
Query Account's Data Source Permissions	Retrieves the data source permission groups for a specified account, including environment list, data source details, and permission items.
Query Role's Data Source Permissions	Retrieves the data source permissions for a specified role, including environments, data sources, and permission actions.
Query Roles with Target Data Source Permissions	Specifies a data source and retrieves all roles with permissions for that data source.
Query Accounts with Target Data Source Permissions	Specifies a data source and retrieves all accounts with permissions for that data source.
Query Permission Application Records for Target Data Source	Specifies a data source and retrieves all submitted permission application records for it.

Audit Log APIs

API Name	Description
Query Operation Logs	Paginated query of NineData operation audit logs, supporting filtering by account, time range, module, event type, and more.
Query SQL Execution Logs	Paginated query of NineData SQL execution logs, supporting filtering by account, time, data source, database/table, SQL type, and other criteria.

Data Replication Task APIs

API Name	Description
Query Replication Tasks	Queries replication tasks by page, with filters for task ID, status, data source, task type, bidirectional task group, and name keyword.
Query Replication Task Status	Queries the status of a specified replication task, including the current subtask, progress, and incremental delay.
Create Replication Task	Creates a one-way or bidirectional replication task and configures replication options and object scope.
Query Replication Task Options	Queries the current replication options of a specified replication task.
Update Replication Task	Updates the data sources, replication options, and object scope of a specified replication task.
Precheck Replication Task	Starts the precheck for a specified replication task.
Query Replication Task Precheck Status	Queries the precheck status and check item results of a specified replication task.
Start Replication Task	Starts a specified replication task.
Query Replication Task Metrics	Queries monitoring metrics of a specified replication task within a time range.
Suspend Replication Task	Suspends a running replication task.
Terminate Replication Task	Terminates a specified replication task.
Delete Replication Task	Deletes a specified replication task.

Data Comparison Task APIs

API Name	Description
Create Data Comparison Task	Create a data comparison task and specify the source, target, and database/table scope.
Start Data Comparison Task	Start the specified data comparison task.
Query Data Comparison Main Task Details	Query the status, name, and latest related subtask information of a data comparison main task.
Query Data Comparison Subtask Details	Query the execution result and difference statistics of a data comparison subtask.
Stop Data Comparison Task	Stop the specified data comparison task.
Delete Data Comparison Task	Delete the specified data comparison task.

Task Monitoring and Log APIs

API Name	Description
Query Task Metrics	Queries monitoring metrics for a data replication task or a data comparison task.
Query Task Logs	Queries runtime logs for a data replication task or a data comparison task.

OpenAPI Interface Documentation

Introduction to NineData OpenAPI​

Request Header Parameters​

Timestamp Specification​

Generating Request Signature​

Quick Integration Process​

Interface Call Examples​

Interface List​