REST API

To support the development of various types of platforms, TDengine provides an API that conforms to RESTful design standards, known as the REST API. To minimize the learning curve, unlike other database REST APIs, TDengine directly operates the database through SQL statements included in the HTTP POST request body, requiring only a URL.

note

One difference from the native connector is that the RESTful interface is stateless, so the USE db_name command has no effect. All references to table names and supertable names must specify the database name prefix. It supports specifying the db_name in the RESTful URL; in this case, if the SQL statement does not specify a database name prefix, the db_name specified in the URL will be used.

Installation

The RESTful interface does not depend on any TDengine libraries, so no TDengine libraries need to be installed on the client, as long as the client's development language supports HTTP protocol. TDengine's RESTful API is provided by taosAdapter. Before using the RESTful API, ensure that the taosAdapter is running properly.

Verification

If the TDengine server is already installed, you can verify it as follows.

Use the curl tool (ensure it is installed) in an Ubuntu environment to verify whether the RESTful interface is functioning correctly. Before verification, ensure that the taosAdapter service is running. In Linux systems, this service is managed by systemd by default, and you can start it with the command systemctl start taosadapter.

The following example lists all databases. Please replace h1.tdengine.com and 6041 (the default value) with the actual FQDN and port number of the running TDengine service:

curl -L -H "Authorization: Basic cm9vdDp0YW9zZGF0YQ==" \
  -d "select name, ntables, status from information_schema.ins_databases;" \
  h1.tdengine.com:6041/rest/sql

The following return value indicates successful verification:

{
    "code": 0,
    "column_meta": [
        [
            "name",
            "VARCHAR",
            64
        ],
        [
            "ntables",
            "BIGINT",
            8
        ],
        [
            "status",
            "VARCHAR",
            10
        ]
    ],
    "data": [
        [
            "information_schema",
            16,
            "ready"
        ],
        [
            "performance_schema",
            9,
            "ready"
        ]
    ],
    "rows": 2
}

HTTP Request Format

http://<fqdn>:<port>/rest/sql/[db_name][?tz=timezone[&req_id=req_id][&row_with_meta=true]]

Parameter descriptions:

• fqdn: FQDN or IP address of any host in the cluster.
• port: The value of the httpPort configuration item in the configuration file, defaulting to 6041.
• db_name: An optional parameter that specifies the default database name for the SQL statement to be executed.
• tz: An optional parameter that specifies the timezone for the returned time, following the IANA Time Zone rules, such as America/New_York.
• req_id: An optional parameter that specifies the request ID, which can be used for tracing.
• row_with_meta: An optional parameter that specifies whether each row of data carries the column names, defaulting to false. (Supported starting from version 3.3.2.0)

For example: http://h1.taos.com:6041/rest/sql/test points to the address h1.taos.com:6041, and sets the default database name to test.

The HTTP request header must include authentication information. TDengine supports both Basic and custom authentication mechanisms, and standard secure digital signature mechanisms for authentication will be provided in future versions.

• Custom authentication information is as follows:

  Authorization: Taosd <TOKEN>

• Basic authentication information is as follows:

  Authorization: Basic <TOKEN>

The body of the HTTP request contains a complete SQL statement. The data table in the SQL statement should provide the database prefix, such as db_name.tb_name. If the table name does not have a database prefix and the database name is not specified in the URL, the system will return an error. This is because the HTTP module is merely a simple forwarder and has no concept of the current DB.

To initiate an HTTP request using the custom authentication method with curl, the syntax is as follows:

curl -L -H "Authorization: Basic <TOKEN>" -d "<SQL>" <ip>:<PORT>/rest/sql/[db_name][?tz=timezone[&req_id=req_id][&row_with_meta=true]]

Alternatively,

curl -L -u username:password -d "<SQL>" <ip>:<PORT>/rest/sql/[db_name][?tz=timezone[&req_id=req_id][&row_with_meta=true]]

Where TOKEN is the Base64 encoded string of {username}:{password}, for example, root:taosdata encoded becomes cm9vdDp0YW9zZGF0YQ==.

HTTP Return Format

HTTP Response Codes

By default, taosAdapter will return a 200 response code for most C interface call errors, but the HTTP body will contain error information. Starting from TDengine 3.0.3.0, taosAdapter provides the configuration parameter httpCodeServerError to set whether to return non-200 HTTP response codes when C interfaces return errors. Regardless of whether this parameter is set, the response body will always contain detailed error codes and messages.

When httpCodeServerError is false:

Classification Description	HTTP Response Code
C interface call success	200
C interface call error, not an authentication error	200
HTTP request URL parameter error	400
C interface call authentication error	401
Interface does not exist	404
Insufficient system resources	503

When httpCodeServerError is true:

Classification Description	HTTP Response Code
C interface call success	200
HTTP request URL parameter error and C interface call parameter parsing error	400
C interface call authentication error	401
Interface does not exist	404
C interface call network unavailable error	502
Insufficient system resources	503
Other C interface call errors	500

C interface parameter parsing related error codes:

• TSDB_CODE_TSC_SQL_SYNTAX_ERROR (0x0216)
• TSDB_CODE_TSC_LINE_SYNTAX_ERROR (0x021B)
• TSDB_CODE_PAR_SYNTAX_ERROR (0x2600)
• TSDB_CODE_TDB_TIMESTAMP_OUT_OF_RANGE (0x060B)
• TSDB_CODE_TSC_VALUE_OUT_OF_RANGE (0x0224)
• TSDB_CODE_PAR_INVALID_FILL_TIME_RANGE (0x263B)

C interface authentication related error codes:

• TSDB_CODE_MND_USER_ALREADY_EXIST (0x0350)
• TSDB_CODE_MND_USER_NOT_EXIST (0x0351)
• TSDB_CODE_MND_INVALID_USER_FORMAT (0x0352)
• TSDB_CODE_MND_INVALID_PASS_FORMAT (0x0353)
• TSDB_CODE_MND_NO_USER_FROM_CONN (0x0354)
• TSDB_CODE_MND_TOO_MANY_USERS (0x0355)
• TSDB_CODE_MND_INVALID_ALTER_OPER (0x0356)
• TSDB_CODE_MND_AUTH_FAILURE (0x0357)

C interface network unavailable related error codes:

• TSDB_CODE_RPC_NETWORK_UNAVAIL (0x000B)

Error codes and descriptions can be found in Error Codes.

HTTP Body Structure

Successfully Executed Insert

Example:

{
  "code": 0,
  "column_meta": [["affected_rows", "INT", 4]],
  "data": [[0]],
  "rows": 1
}

Description:

• code: (int) 0 indicates success.
• column_meta: ([1][3]any) returns only [["affected_rows", "INT", 4]].
• rows: (int) returns only 1.
• data: ([][]any) returns the number of affected rows.

Successfully Executed Query

Example:

{
  "code": 0,
  "column_meta": [
    ["ts", "TIMESTAMP", 8],
    ["count", "BIGINT", 8],
    ["endpoint", "VARCHAR", 45],
    ["status_code", "INT", 4],
    ["client_ip", "VARCHAR", 40],
    ["request_method", "VARCHAR", 15],
    ["request_uri", "VARCHAR", 128]
  ],
  "data": [
    [
      "2022-06-29T05:50:55.401Z",
      2,
      "LAPTOP-NNKFTLTG:6041",
      200,
      "172.23.208.1",
      "POST",
      "/rest/sql"
    ],
    [
      "2022-06-29T05:52:16.603Z",
      1,
      "LAPTOP-NNKFTLTG:6041",
      200,
      "172.23.208.1",
      "POST",
      "/rest/sql"
    ],
    [
      "2022-06-29T06:28:14.118Z",
      1,
      "LAPTOP-NNKFTLTG:6041",
      200,
      "172.23.208.1",
      "POST",
      "/rest/sql"
    ],
    [
      "2022-06-29T05:52:16.603Z",
      2,
      "LAPTOP-NNKFTLTG:6041",
      401,
      "172.23.208.1",
      "POST",
      "/rest/sql"
    ]
  ],
  "rows": 4
}

Description:

• code: (int) 0 indicates success.
• column_meta: ([][3]any) Column information, each column is described by three values: column name (string), column type (string), and type length (int).
• rows: (int) Number of returned rows.
• data: ([][]any) Specific data content (the time format supports only RFC3339, with the result set being in UTC).

Column types use the following strings:

• "NULL"
• "BOOL"
• "TINYINT"
• "SMALLINT"
• "INT"
• "BIGINT"
• "FLOAT"
• "DOUBLE"
• "VARCHAR"
• "TIMESTAMP"
• "NCHAR"
• "TINYINT UNSIGNED"
• "SMALLINT UNSIGNED"
• "INT UNSIGNED"
• "BIGINT UNSIGNED"
• "JSON"
• "VARBINARY"
• "GEOMETRY"

The VARBINARY and GEOMETRY types return data as Hex strings. Example:

Prepare Data

create database demo
use demo
create table t(ts timestamp,c1 varbinary(20),c2 geometry(100))
insert into t values(now,'\x7f8290','point(100 100)')

Execute Query

curl --location 'http://<fqdn>:<port>/rest/sql' \
--header 'Content-Type: text/plain' \
--header 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' \
--data 'select * from demo.t'

Return Result

{
    "code": 0,
    "column_meta": [
        [
            "ts",
            "TIMESTAMP",
            8
        ],
        [
            "c1",
            "VARBINARY",
            20
        ],
        [
            "c2",
            "GEOMETRY",
            100
        ]
    ],
    "data": [
        [
            "2023-11-01T06:28:15.210Z",
            "7f8290",
            "010100000000000000000059400000000000005940"
        ]
    ],
    "rows": 1
}

• 010100000000000000000059400000000000005940 is the Well-Known Binary (WKB) format for point(100 100).

Error

Example:

{
  "code": 9728,
  "desc": "syntax error near \"1\""
}

Description:

• code: (int) Error code.
• desc: (string) Error description.

Refer to the Error Codes for error codes and descriptions.

Return Key-Value Format Data

When the URL parameter row_with_meta=true is specified, the data in the returned data will change from an array format to an object format, where the object's key is the column name and the value is the data, as shown below:

Example of Insert Data Return

{
    "code": 0,
    "column_meta": [
        [
            "affected_rows",
            "INT",
            4
        ]
    ],
    "data": [
        {
            "affected_rows": 1
        }
    ],
    "rows": 1
}

Example of Query Data Return

{
    "code": 0,
    "column_meta": [
        [
            "ts",
            "TIMESTAMP",
            8
        ],
        [
            "current",
            "FLOAT",
            4
        ],
        [
            "voltage",
            "INT",
            4
        ],
        [
            "phase",
            "FLOAT",
            4
        ],
        [
            "groupid",
            "INT",
            4
        ],
        [
            "location",
            "VARCHAR",
            24
        ]
    ],
    "data": [
        {
            "ts": "2017-07-14T02:40:00.000Z",
            "current": -2.498076,
            "voltage": 0,
            "phase": -0.846025,
            "groupid": 8,
            "location": "California.Sunnyvale"
        }
    ],
    "rows": 1
}

Custom Authorization Code

The HTTP request needs to include the authorization code <TOKEN> for identity recognition. The authorization code is usually provided by the administrator and can be obtained simply by sending an HTTP GET request as follows:

curl http://<fqdn>:<port>/rest/login/<username>/<password>

Where fqdn is the FQDN or IP address of the TDengine database, port is the port number of the TDengine service, username is the database username, and password is the database password. The return value will be in JSON format, and the meanings of each field are as follows:

• status: The flag indicating the result of the request.
• code: The return value code.
• desc: The authorization code.

Example to Get Authorization Code:

curl http://192.168.0.1:6041/rest/login/root/taosdata

Return Value:

{
  "code": 0,
  "desc": "/KfeAzX/f9na8qdtNZmtONryp201ma04bEl8LcvLUd7a8qdtNZmtONryp201ma04"
}

Usage Examples

• Query all records of table d1001 in the demo library:

  curl -L -H "Authorization: Basic cm9vdDp0YW9zZGF0YQ==" -d "select * from demo.d1001" 192.168.0.1:6041/rest/sql
  curl -L -H "Authorization: Taosd /KfeAzX/f9na8qdtNZmtONryp201ma04bEl8LcvLUd7a8qdtNZmtONryp201ma04" -d "select * from demo.d1001" 192.168.0.1:6041/rest/sql

  Return Value:

  {
      "code": 0,
      "column_meta": [
          [
              "ts",
              "TIMESTAMP",
              8
          ],
          [
              "current",
              "FLOAT",
              4
          ],
          [
              "voltage",
              "INT",
              4
          ],
          [
              "phase",
              "FLOAT",
              4
          ]
      ],
      "data": [
          [
              "2022-07-30T06:44:40.32Z",
              10.3,
              219,
              0.31
          ],
          [
              "2022-07-30T06:44:41.32Z",
              12.6,
              218,
              0.33
          ]
      ],
      "rows": 2
  }

• Create library demo:

  curl -L -H "Authorization: Basic cm9vdDp0YW9zZGF0YQ==" -d "create database demo" 192.168.0.1:6041/rest/sql
  curl -L -H "Authorization: Taosd /KfeAzX/f9na8qdtNZmtONryp201ma04bEl8LcvLUd7a8qdtNZmtONryp201ma04" -d "create database demo" 192.168.0.1:6041/rest/sql

  Return Value:

  {
      "code": 0,
      "column_meta": [
          [
              "affected_rows",
              "INT",
              4
          ]
      ],
      "data": [
          [
              0
          ]
      ],
      "rows": 1
  }

Differences Between REST API in TDengine 2.x and 3.0

URI

URI	TDengine 2.x	TDengine 3.0
/rest/sql	Supported	Supported (Response codes and body differ)
/rest/sqlt	Supported	No longer supported
/rest/sqlutc	Supported	No longer supported

HTTP Code

HTTP Code	TDengine 2.x	TDengine 3.0	Notes
200	Supported	Supported	Correct return and taosc interface error return
400	Not supported	Supported	Parameter error return
401	Not supported	Supported	Authentication failure
404	Supported	Supported	Interface does not exist
500	Not supported	Supported	Internal error
503	Supported	Supported	Insufficient system resources

Response Codes and Body

TDengine 2.x Response Codes and Body

{
  "status": "succ",
  "head": [
    "name",
    "created_time",
    "ntables",
    "vgroups",
    "replica",
    "quorum",
    "days",
    "keep1,keep2,keep(D)",
    "cache(MB)",
    "blocks",
    "minrows",
    "maxrows",
    "wallevel",
    "fsync",
    "comp",
    "precision",
    "status"
  ],
  "data": [
    [
      "log",
      "2020-09-02 17:23:00.039",
      4,
      1,
      1,
      1,
      10,
      "30,30,30",
      1,
      3,
      100,
      4096,
      1,
      3000,
      2,
      "us",
      "ready"
    ]
  ],
  "rows": 1
}

  "data": [
        [
            "information_schema",
            16,
            "ready"
        ],
        [
            "performance_schema",
            9,
            "ready"
        ]
    ],

TDengine 3.0 Response Codes and Body

{
    "code": 0,
    "column_meta": [
        [
            "name",
            "VARCHAR",
            64
        ],
        [
            "ntables",
            "BIGINT",
            8
        ],
        [
            "status",
            "VARCHAR",
            10
        ]
    ],
    "data": [
        [
            "information_schema",
            16,
            "ready"
        ],
        [
            "performance_schema",
            9,
            "ready"
        ]
    ],
    "rows": 2
}