To support the development of various types of applications and platforms, TDengine provides an API that conforms to REST principles; namely REST API. To minimize the learning cost, unlike REST APIs for other database engines, TDengine allows insertion of SQL commands in the BODY of an HTTP POST request, to operate the database.
:::note
One difference from the native connector is that the REST interface is stateless and so the `USE db_name` command has no effect. All references to table names and super table names need to specify the database name in the prefix. TDengine supports specification of the db_name in RESTful URL. If the database name prefix is not specified in the SQL command, the `db_name` specified in the URL will be used.
:::
## Installation
The REST interface does not rely on any TDengine native library, so the client application does not need to install any TDengine libraries. The client application's development language only needs to support the HTTP protocol.
## Verification
To verify accessing TDengine Cloud service, it can be as follows:
The following example is in an Ubuntu environment and uses the `curl` tool to verify that the REST interface is working. Note that the `curl` tool may need to be installed in your environment.
The following example lists all databases on the host `TDengine Cloud URL`. If you are accessing TDengine Cloud, you need to use given token.
```bash
curl -L\
-d"select name, ntables, status from information_schema.ins_databases;"\
<TDengine Service URL>/rest/sql?token=<TDengine Cloud Token>
```
The following return value results indicate that the verification passed.
- db_name: Optional parameter that specifies the default database name for the executed SQL command.
- token: use to access TDengine cloud service.
For example, `http://gw-aws.cloud.tdengine.com:80/rest/sql/test?token=xxxxxxxxx` is a URL to `gw-aws.cloud.tdengine:80` and sets the default database name to `test`.
TDengine supports both Basic authentication and custom authentication mechanisms, and subsequent versions will provide a standard secure digital signature mechanism for authentication.
The HTTP request's BODY is a complete SQL command, and the data table in the SQL statement should be provided with a database prefix, e.g., `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 response an error because the HTTP module is a simple forwarder and has no awareness of the current DB.
Use `curl` to initiate an HTTP request with a custom authentication method, with the following syntax.
| 200 | Success. (Also used for C interface errors.) |
| 400 | Parameter error |
| 401 | Authentication failure |
| 404 | Interface not found |
| 500 | Internal error |
| 503 | Insufficient system resources |
### HTTP body structure
#### Successful Operation
Example:
```json
{
"code":0,
"column_meta":[["affected_rows","INT",4]],
"data":[[0]],
"rows":1
}
```
Description:
- code: (`int`) 0 indicates success.
- column_meta: (`[1][3]any`) Only returns `[["affected_rows", "INT", 4]]`.
- rows: (`int`) Only returns `1`.
- data: (`[][]any`) Returns the number of rows affected.
#### Successful Query
Example:
```json
{
"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 with three values: column name (string), column type (string), and type length (int).
- rows: (`int`) The number of rows returned.
- data: (`[][]any`)
The following types may be returned:
- "NULL"
- "BOOL"
- "TINYINT"
- "SMALLINT"
- "INT"
- "BIGINT"
- "FLOAT"
- "DOUBLE"
- "VARCHAR"
- "TIMESTAMP"
- "NCHAR"
- "TINYINT UNSIGNED"
- "SMALLINT UNSIGNED"
- "INT UNSIGNED"
- "BIGINT UNSIGNED"
- "JSON"
#### Errors
Example:
```json
{
"code":9728,
"desc":"syntax error near \"1\""
}
```
Description:
- code: (`int`) Error code.
- desc: (`string`): Error code description.
## Usage examples
- query all records from table d1001 of database demo
