Call NineData OpenAPI

Use NineData OpenAPI to integrate external systems with NineData workflows, including data source management, permissions, roles, approval groups, audit logs, replication tasks, and comparison tasks.

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 OpenAPI provides REST-style endpoints for managing NineData resources programmatically.

Base URL

For SaaS, use this base URL:

https://console.ninedata.cloud

For private deployments, use the domain or endpoint provided by your NineData administrator.

Request Header Parameters

Parameter Name	Required	Type	Description
access-key-id	Yes	string	The AccessKey ID issued by NineData. View it in User Management in 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

• Get the server time from this endpoint:

  curl https://console.ninedata.cloud/openapi/now

Generating Request Signature

Generate the request signature by concatenating the API path, SecretKey, and current timestamp, and then calculating the SHA-256 digest.

1. In User Management in the NineData ConsoleNineData Console, click Enable AccessKey in the Operations column for the target user, and record the SecretKey.

2. Build the string to sign in this format.

   <Interface Address> + / + <SecretKey> + & + <Current Timestamp>

   Example: /openapi/v1/region/list/Na12ssaaggffdd&2025-04-09T17:15:33Z

3. Calculate the SHA-256 digest 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}'

Prerequisites

• You have enabled AccessKey for the target NineData user.
• You have recorded the AccessKey and SecretKey.
• The timestamp used to generate the signature is exactly the same as the timestamp sent in the request header.
• On Windows, use Git Bash or another shell that supports sha256sum.

Procedure

1. Obtain Credentials: Sign in to the NineData Console, enable AccessKey in User Management, and then record the AccessKey and SecretKey.

   

   

2. Obtain the current system timestamp.

3. Calculate the signature: Execute echo -n "/openapi/v1/region/list/<SecretKey>&<Current System Timestamp>" | sha256sum | awk '{print $1}' in the command line.

4. Send the API request with the generated headers. For example:

   • GET request: curl https://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" https://console.ninedata.cloud/openapi/v1/datasource/delete -d '{"datasourceId":"<Data Source ID>"}'

Result

If the signature, timestamp, and request body are valid, NineData returns the endpoint response. If the signature or timestamp is invalid, regenerate the timestamp and signature, then retry the request.

Next steps

• Start with read-only endpoints such as GET /openapi/now and GET /openapi/v1/region/list.
• Store AccessKey and SecretKey in a secure secret manager instead of source code.
• Review the API-specific topics below before creating, updating, or deleting resources.

Interface Call Examples

This section provides example code for calling NineData OpenAPI.

Bash Example

#!/bin/bash

set -e

echo "current time : $(date)"

baseUrl="https://console.ninedata.cloud"

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

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

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

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

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

  curl -H "access-key-id:$accessKeyId" \
         -H "timestamp:$timestamp" \
         -H "signature:$signature" \
         -H "Content-type:application/json" \
         "$baseUrl$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 baseUrl = "https://console.ninedata.cloud";
        String accessKeyId = "<accessKeyId>";
        String accessKeySecret = "<accessKeySecret>";

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

        // POST example
        sendPost(baseUrl, "/openapi/v1/datasource/delete",
                "{\"datasourceId\":\"<datasourceId>\"}", accessKeyId, accessKeySecret);
        
        sendPost(baseUrl, "/openapi/v1/datasource/update",
                "{\"datasourceId\":\"<datasourceId>\",\"name\":\"Data Source\"}", accessKeyId, accessKeySecret);
        
        sendPost(baseUrl, "/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 baseUrl, String api, String params,
                              String accessKeyId, String accessKeySecret) {
        try {
            String timestamp = getTimestamp();
            String signature = generateSignature(api, accessKeySecret, timestamp);
            
            URL url = new URL(baseUrl + 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 baseUrl, String api, String jsonBody,
                               String accessKeyId, String accessKeySecret) {
        try {
            String timestamp = getTimestamp();
            String signature = generateSignature(api, accessKeySecret, timestamp);
            
            URL url = new URL(baseUrl + 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 a data source already added to NineData, including its name, account, password, connection address, port, and environment.
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.

Database 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.
Start Data Comparison Precheck	Starts the precheck for a specified data comparison task.
Query Data Comparison Precheck Status	Queries the precheck status and check item results of a data comparison task.
Query Data Comparison Table Summary	Queries table-level comparison results for a specified execution of a data comparison task.
Query Data Comparison Difference Details	Queries inconsistent record details for a specified table.
Query Data Comparison Correction SQL	Queries correction SQL statements for inconsistent data in a specified table.
Stop Data Comparison Task	Stop the specified data comparison task.
Delete Data Comparison Task	Delete the specified data comparison task.
Create Schema Comparison Task	Create a schema comparison task and specify the source, target, and object scope.
Start Schema Comparison Precheck	Start the precheck for a specified schema comparison task.
Query Schema Comparison Precheck Status	Query the precheck status and check item results of a schema comparison task.
Start Schema Comparison Task	Start a specified schema comparison task.
Stop Schema Comparison Task	Stop a specified schema comparison task.
Delete Schema Comparison Task	Delete a specified schema comparison task.
List Schema Comparison Tasks	Query schema comparison tasks under the current account by page.
Query Schema Comparison Main Task Details	Query basic information and the latest execution information for a schema comparison main task.
Query Schema Comparison Subtask Details	Query the runtime status of a schema comparison subtask.
Query Schema Comparison Object Results	Query object-level comparison results for a schema comparison execution.
Query Schema Comparison Correction SQL	Query correction SQL for an inconsistent schema comparison object.

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.