RestAPI V1

IoTDB's RESTful service can be used for querying, writing, and management operations. It uses the OpenAPI standard to define interfaces and generate frameworks.

1. Enabling RESTful Service

The RESTful service is disabled by default. To enable it, locate the conf/iotdb-system.properties file in the IoTDB installation directory, set enable_rest_service to true, and then restart the datanode process.

enable_rest_service=true

2. Authentication

Except for the health check endpoint /ping, the RESTful service uses basic authentication. Each URL request must include the header 'Authorization':'Basic' + base64.encode(username + ':' + password).

In the example, the username is root and the password is root. The corresponding Basic authentication header format is:

Authorization : Basic cm9vdDpyb290

• If the username or password authentication fails, the following information is returned:

  • HTTP status code: 801

  • Response body:

    {"code":801,"message":"WRONG_LOGIN_PASSWORD"}

• If the Authorization header is not set, the following information is returned:

  • HTTP status code: 800

  • Response body:

    {"code":800,"message":"INIT_AUTH_ERROR"}

3. Interface Definitions

3.1 Ping

The /ping endpoint can be used for online service health checks.

• Request Method: GET

• Request Path: http://ip:port/ping

• Example Request:

    curl http://127.0.0.1:18080/ping

• HTTP Status Codes:

  • 200: The service is working normally and can accept external requests.

  • 503: The service is experiencing issues and cannot accept external requests.

  | Parameter Name | Type | Description |
  | :------------- | :------ | :--------------- |
  | code | integer | Status Code |
  | message | string | Code Information |

• Response Example:

  • When the HTTP status code is 200:

    {  "code": 200,  "message": "SUCCESS_STATUS"}

  • When the HTTP status code is 503:

    {  "code": 500,  "message": "thrift service is unavailable"}

Note: The /ping endpoint does not require authentication.

3.2 Query Interface

• Request Path: /rest/table/v1/query

• Request Method: POST

• Request Format:

  • Header: application/json

  • Request Parameters:

    | Parameter Name | Type | Required | Description |
    | :------------- | :----- | :------- | :----------------------------------------------------------- |
    | database | string | Yes | Database name |
    | sql | string | Yes | SQL query |
    | row_limit | int | No | Maximum number of rows to return in a single query. If not set, the default value from the configuration file (rest_query_default_row_size_limit) is used. If the result set exceeds this limit, status code 411 is returned. |

• Response Format:

  | Parameter Name | Type | Description |
  | :------------- | :---- | :----------------------------------------------------------- |
  | column_names | array | Column names |
  | data_types | array | Data types of each column |
  | values | array | A 2D array where the first dimension represents rows, and the second dimension represents columns. Each element corresponds to a column, with the same length as column_names. |

• Example Request:

    curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"database":"test","sql":"select s1,s2,s3 from test_table"}' http://127.0.0.1:18080/rest/table/v1/query

• Example Response:

    {
        "column_names": [
            "s1",
            "s2",
            "s3"
        ],
        "data_types": [
            "STRING",
            "BOOLEAN",
            "INT32"
        ],
        "values": [
            [
                "a11",
                true,
                2024
            ],
            [
                "a11",
                false,
                2025
            ]
        ]
    }

3.3 Non-Query Interface

• Request Path: /rest/table/v1/nonQuery

• Request Method: POST

• Request Format:

  • Header: application/json

  • Request Parameters:

    | Parameter Name | Type | Required | Description |
    | :------------- | :----- | :------- | :------------ |
    | sql | string | Yes | SQL statement |
    | database | string | No | Database name |

• Response Format:

  | Parameter Name | Type | Description |
  | :------------- | :------ | :---------- |
  | code | integer | Status code |
  | message | string | Message |

• Example Requests:

  • Create a database:

    curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"sql":"create database test","database":""}' http://127.0.0.1:18080/rest/table/v1/nonQuery

  • Create a table test_table in the test database:

    curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"sql":"CREATE TABLE table1 (time TIMESTAMP TIME,region STRING TAG,plant_id STRING TAG,device_id STRING TAG,model_id STRING ATTRIBUTE,maintenance STRING ATTRIBUTE,temperature FLOAT FIELD,humidity FLOAT FIELD,status Boolean FIELD,arrival_time TIMESTAMP FIELD) WITH (TTL=31536000000)","database":"test"}' http://127.0.0.1:18080/rest/table/v1/nonQuery

• Example Response:

    {
      "code": 200,
      "message": "SUCCESS_STATUS"
    }

3.4 Batch Write Interface

• Request Path: /rest/table/v1/insertTablet

• Request Method: POST

• Request Format:

  • Header: application/json

  • Request Parameters:

    | Parameter Name | Type | Required | Description |
    | :------------------ | :----- | :------- | :----------------------------------------------------------- |
    | database | string | Yes | Database name |
    | table | string | Yes | Table name |
    | column_names | array | Yes | Column names |
    | column_catogories | array | Yes | Column categories (TAG, FIELD, ATTRIBUTE) |
    | data_types | array | Yes | Data types |
    | timestamps | array | Yes | Timestamp column |
    | values | array | Yes | Value columns. Each column's values can be null. A 2D array where the first dimension corresponds to timestamps, and the second dimension corresponds to columns. |

• Response Format:

  | Parameter Name | Type | Description |
  | :------------- | :------ | :---------- |
  | code | integer | Status code |
  | message | string | Message |

• Example Request:

    curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"database":"test","column_catogories":["TAG","FIELD","FIELD"],"timestamps":[1739702535000,1739789055000],"column_names":["s1","s2","s3"],"data_types":["STRING","BOOLEAN","INT32"],"values":[["a11",true,2024],["a11",false,2025]],"table":"test_table"}' http://127.0.0.1:18080/rest/table/v1/insertTablet

• Example Response:

    {
      "code": 200,
      "message": "SUCCESS_STATUS"
    }

4. Configuration

The configuration file is located in iotdb-system.properties.

• Set enable_rest_service to true to enable the module, or false to disable it. The default value is false.

    enable_rest_service=true

• Only effective when enable_rest_service=true. Set rest_service_port to a number (1025~65535) to customize the REST service socket port. The default value is 18080.

    rest_service_port=18080

• Set enable_swagger to true to enable Swagger for displaying REST interface information, or false to disable it. The default value is false.

    enable_swagger=false

• The maximum number of rows that can be returned in a single query. If the result set exceeds this limit, only the rows within the limit will be returned, and status code 411 will be returned.

    rest_query_default_row_size_limit=10000

• Expiration time for caching client login information (used to speed up user authentication, in seconds, default is 8 hours).

    cache_expire_in_seconds=28800

• Maximum number of users stored in the cache (default is 100).

    cache_max_num=100

• Initial cache capacity (default is 10).

    cache_init_num=10

• Whether to enable SSL configuration for the REST service. Set enable_https to true to enable it, or false to disable it. The default value is false.

    enable_https=false

• Path to the keyStore (optional).

    key_store_path=

• Password for the keyStore (optional).

    key_store_pwd=

• Path to the trustStore (optional).

    trust_store_path=""

• Password for the trustStore (optional).

    trust_store_pwd=""

• SSL timeout time, in seconds.

    idle_timeout_in_seconds=5000