02-rest-api.mdx 8.8 KB
Newer Older
1 2 3 4
---
title: REST API
---

D
danielclow 已提交
5
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. 
6

D
danielclow 已提交
7 8
:::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.
9 10 11 12
:::

## Installation

13
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. The REST interface is provided by [taosAdapter](../taosadapter), to use REST interface you need to make sure `taosAdapter` is running properly.
14 15 16 17 18

## Verification

If the TDengine server is already installed, it can be verified as follows:

19
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.
20

G
gccgdb1234 已提交
21
The following example lists all databases on the host h1.tdengine.com. To use it in your environment, replace `h1.tdengine.com` and `6041` (the default port) with the actual running TDengine service FQDN and port number.
22

D
danielclow 已提交
23 24 25
```bash
curl -L -H "Authorization: Basic cm9vdDp0YW9zZGF0YQ==" \
  -d "select name, ntables, status from information_schema.ins_databases;" \
G
gccgdb1234 已提交
26
  h1.tdengine.com:6041/rest/sql
27 28 29 30 31 32
```

The following return value results indicate that the verification passed.

```json
{
D
danielclow 已提交
33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63
    "code": 0,
    "column_meta": [
        [
            "name",
            "VARCHAR",
            64
        ],
        [
            "ntables",
            "BIGINT",
            8
        ],
        [
            "status",
            "VARCHAR",
            10
        ]
    ],
    "data": [
        [
            "information_schema",
            16,
            "ready"
        ],
        [
            "performance_schema",
            9,
            "ready"
        ]
    ],
    "rows": 2
64 65 66 67 68
}
```

## HTTP request URL format

D
danielclow 已提交
69
```text
70 71 72 73 74
http://<fqdn>:<port>/rest/sql/[db_name]
```

Parameter Description:

D
danielclow 已提交
75 76 77
- fqnd: FQDN or IP address of any host in the cluster.
- port: httpPort configuration item in the configuration file, default is 6041.
- db_name: Optional parameter that specifies the default database name for the executed SQL command.
78 79 80 81 82

For example, `http://h1.taos.com:6041/rest/sql/test` is a URL to `h1.taos.com:6041` 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.

D
danielclow 已提交
83
- authentication information is shown below:
84

D
danielclow 已提交
85
  ```text
86 87 88
  Authorization: Taosd <TOKEN>
  ```

D
danielclow 已提交
89
- Basic authentication information is shown below:
90

D
danielclow 已提交
91
  ```text
92 93 94 95 96 97 98 99
  Authorization: Basic <TOKEN>
  ```

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.

```bash
Z
Zhengmao Zhu 已提交
100
curl -L -H "Authorization: Basic <TOKEN>" -d "<SQL>" <ip>:<PORT>/rest/sql/[db_name]
101 102
```

D
danielclow 已提交
103
or
104 105

```bash
Z
Zhengmao Zhu 已提交
106
curl -L -u username:password -d "<SQL>" <ip>:<PORT>/rest/sql/[db_name]
107 108
```

D
danielclow 已提交
109
where `TOKEN` is the string after Base64 encoding of `{username}:{password}`, e.g. `root:taosdata` is encoded as `cm9vdDp0YW9zZGF0YQ==`..
110 111 112

## HTTP Return Format

D
danielclow 已提交
113 114 115 116 117 118 119 120 121 122 123 124 125
### HTTP Response Code

| **Response Code** | **Description**         |
|-------------------|----------------|
| 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

sangshuduo's avatar
sangshuduo 已提交
126
#### Successful Insert Operation
D
danielclow 已提交
127 128

Example:
129 130 131

```json
{
D
danielclow 已提交
132 133 134 135 136 137 138 139 140 141 142 143 144 145
  "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.

sangshuduo's avatar
sangshuduo 已提交
146
#### Successful Query Operation
D
danielclow 已提交
147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170

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"
171
    ],
D
danielclow 已提交
172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237
    [
      "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\""
238 239 240 241 242
}
```

Description:

D
danielclow 已提交
243 244
- code: (`int`) Error code.
- desc: (`string`): Error code description.
245 246 247 248 249 250 251 252 253 254 255

## Custom Authorization Code

HTTP requests require an authorization code `<TOKEN>` for identification purposes. The administrator usually provides the authorization code, and it can be obtained simply by sending an ``HTTP GET`` request as follows:

```bash
curl http://<fqnd>:<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. `password` is the database password. The return value is in `JSON` format, and the meaning of each field is as follows.

D
danielclow 已提交
256 257 258
- status: flag bit of the request result.
- code: return value code.
- desc: authorization code.
259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275

Example of getting authorization code.

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

Response body:

```json
{
  "status": "succ",
  "code": 0,
  "desc": "/KfeAzX/f9na8qdtNZmtONryp201ma04bEl8LcvLUd7a8qdtNZmtONryp201ma04"
}
```

D
danielclow 已提交
276
## Usage examples
277 278 279 280

- query all records from table d1001 of database demo

  ```bash
Z
Zhengmao Zhu 已提交
281
  curl -L -H "Authorization: Basic cm9vdDp0YW9zZGF0YQ==" -d "select * from demo.d1001" 192.168.0.1:6041/rest/sql
282 283 284 285 286 287
  ```

  Response body:

  ```json
  {
D
danielclow 已提交
288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325
      "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
326 327 328 329 330 331
  }
  ```

- Create database demo:

  ```bash
Z
Zhengmao Zhu 已提交
332
  curl -L -H "Authorization: Basic cm9vdDp0YW9zZGF0YQ==" -d "create database demo" 192.168.0.1:6041/rest/sql
333 334 335 336 337 338
  ```

  Response body:

  ```json
  {
D
danielclow 已提交
339 340 341 342 343 344 345 346 347 348 349 350 351 352
      "code": 0,
      "column_meta": [
          [
              "affected_rows",
              "INT",
              4
          ]
      ],
      "data": [
          [
              0
          ]
      ],
      "rows": 1
353 354 355
  }
  ```

D
danielclow 已提交
356
## Reference
357

D
danielclow 已提交
358
[taosAdapter](/reference/taosadapter/)