RestAPI V1

About 4 min

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.

Note: As of version V2.0.8.2, the TimechoDB installation package does not include the REST service JAR file by default. Please contact the Timecho team to obtain the corresponding JAR file before using this service, and place it in the timechodb_home/lib or timechodb_home/ext/external_service directory.

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

All RESTful APIs adopt Basic Authentication, except the health check interface /ping.
All requests must carry the Authorization information in the request header.

Authentication Format

Authorization: Basic <base64_string>

The <base64_string> is generated by directly Base64-encoding the string in the format username:password.
Quick generation methods are shown below:

Linux / macOS

echo -n "your_username:your_password" | base64
eg: echo -n "root:TimechoDB@2021" | base64

Windows

# PowerShell
[Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes("username:password"))
eg: [Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes("root:TimechoDB@2021"))

# CMD
powershell "[Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes(\"username:password\"))"
eg: powershell "[Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes(\"root:TimechoDB@2021\"))"

Authentication Example

Default username: root, password: TimechoDB@2021

Concatenated string: root:TimechoDB@2021
Base64 encoded result: cm9vdDpUaW1lY2hvREJAMjAyMQ==
Final Header:

Authorization: Basic cm9vdDpUaW1lY2hvREJAMjAyMQ==

Error Description

Incorrect username or password: returns HTTP status code 801

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

Missing Authorization configuration: returns HTTP status code 800

{"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_categories | 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_categories":["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
```