--- title: REST API --- TDengine provides an API that conforms to REST design standards to support development on various platforms, i.e., the REST API. To minimize learning costs, and unlike other databases' REST API design approaches, TDengine operates on databases directly through HTTP POST requests for SQL statements contained in the BODY, requiring only a URL. See the [video tutorial](https://www.taosdata.com/blog/2020/11/11/1965.html) to use the REST connector. Note: One difference from the native connector is that the RESTful interface is stateless, so the `USE db_name` directive has no effect. All references to table names and super table names need to be specified with a database name prefix. (Starting with version 2.2.0.0, RESTful supports specifying db_name in the RESTful URL, so if the database name prefix is not specified in the SQL statement, the db_name specified in the URL will be used. (db_name.) ## Installation The RESTful interface does not rely on any TDengine libraries, so the client does not need to install any TDengine libraries. The client's development language supports the HTTP protocol. ## Verification If the TDengine server side is already installed, it can be verified as follows: The following is an Ubuntu environment using the curl tool (to confirm that it is installed) to verify that the RESTful interface is working. The following example lists all databases, replacing h1.taosdata.com and 6041 (the default) with the actual running TDengine service FQDN and port number. ```html curl -H 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' -d 'show databases;' h1.taosdata.com:6041/rest/sql ``` The following return value results indicate that the validation passed. ```json { "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 } ``` ## HTTP request URL format ``` http://:/rest/sql/[db_name] ``` Parameter Description. - 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 statement. (supported since version 2.2.0.0) 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. - The custom authentication information is as follows (Let's introduce token later) ``` Authorization: Taosd ``` - Basic authentication information is shown below ``` Authorization: Basic ``` The HTTP request's BODY is a complete SQL statement, and the data table in the SQL statement should be provided with a database prefix, e.g., \. \. 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 because the HTTP module is a simple forwarder and has no concept of the current DB. Use curl to initiate an HTTP Request with a custom authentication method, with the following syntax. ```bash curl -H 'Authorization: Basic ' -d '' :/rest/sql/[db_name] ``` Or ```bash curl -u username:password -d '' :/rest/sql/[db_name] ``` where `TOKEN` is the string after Base64 encoding of `{username}:{password}`, e.g. `root:taosdata` is encoded as `cm9vdDp0YW9zZGF0YQ==` ## HTTP Return Format The return value is in JSON format, as follows: ```json { "status": "succ", "head": ["ts", "current", ...], "column_meta": [["ts",9,8],["current",6,4], ...], "data": [ ["2018-10-03 14:38:05.000", 10.3, ...], ["2018-10-03 14:38:15.000", 12.6, ...] ], "rows": 2 } ``` Description. - status: tell if the operation result is success or failure. - head: the definition of the table, or just one column "affected_rows" if no result set is returned. (As of version 2.0.17.0, it is recommended not to rely on the head return value to determine the data column type but rather use column_meta. In future versions, the head item may be removed from the return value.) - column_meta: this item is added to the return value to indicate the data type of each column in the data with version 2.0.17.0 and later versions. Each column is described by three values: column name, column type, and type length. For example, `["current",6,4]` means that the column name is "current", the column type is 6, which is the float type, and the type length is 4, which is the float type with 4 bytes. If the column type is binary or nchar, the type length indicates the maximum length of content stored in the column, not the length of the specific data in this return value. When the column type is nchar, the type length indicates the number of Unicode characters that can be saved, not bytes. - data: The exact data returned, presented row by row, or just [[affected_rows]] if no result set is returned. The order of the data columns in each row of data is the same as that of the data columns described in column_meta. - rows: Indicates how many rows of data there are. The column types in column_meta are described as follows: - 1:BOOL - 2:TINYINT - 3:SMALLINT - 4:INT - 5:BIGINT - 6:FLOAT - 7:DOUBLE - 8:BINARY - 9:TIMESTAMP - 10:NCHAR ## Custom Authorization Code HTTP requests require an authorization code `` 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://:/rest/login// ``` 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. - status: flag bit of the request result - code: return value code - desc: authorization code 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" } ``` ## For example - query all records from table d1001 of database demo ```bash curl -H 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' -d 'select * from demo.d1001' 192.168.0.1:6041/rest/sql ``` Response body: ```json { "status": "succ", "head": ["ts", "current", "voltage", "phase"], "column_meta": [ ["ts", 9, 8], ["current", 6, 4], ["voltage", 4, 4], ["phase", 6, 4] ], "data": [ ["2018-10-03 14:38:05.000", 10.3, 219, 0.31], ["2018-10-03 14:38:15.000", 12.6, 218, 0.33] ], "rows": 2 } ``` - Create database demo: ```bash curl -H 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' -d 'create database demo' 192.168.0.1:6041/rest/sql ``` Response body: ```json { "status": "succ", "head": ["affected_rows"], "column_meta": [["affected_rows", 4, 4]], "data": [[1]], "rows": 1 } ``` ## Other Uses ### Unix timestamps for result sets When the HTTP request URL uses `sqlt`, the timestamp of the returned result set will be in Unix timestamp format, for example: ```bash curl -H 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' -d 'select * from demo.d1001' 192.168.0.1:6041/rest/sqlt ``` Response body: ```json { "status": "succ", "head": ["ts", "current", "voltage", "phase"], "column_meta": [ ["ts", 9, 8], ["current", 6, 4], ["voltage", 4, 4], ["phase", 6, 4] ], "data": [ [1538548685000, 10.3, 219, 0.31], [1538548695000, 12.6, 218, 0.33] ], "rows": 2 } ``` ### UTC format for the result set When the HTTP request URL uses `sqlutc`, the timestamp of the returned result set will be expressed as a UTC format, for example: ```bash curl -H 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' -d 'select * from demo.t1' 192.168.0.1:6041/rest/sqlutc ``` Respones body: ```json { "status": "succ", "head": ["ts", "current", "voltage", "phase"], "column_meta": [ ["ts", 9, 8], ["current", 6, 4], ["voltage", 4, 4], ["phase", 6, 4] ], "data": [ ["2018-10-03T14:38:05.000+0800", 10.3, 219, 0.31], ["2018-10-03T14:38:15.000+0800", 12.6, 218, 0.33] ], "rows": 2 } ``` ## Important configuration items Only some configuration parameters related to the RESTful interface are listed below. Please see the description in the configuration file for other system parameters. - The port number of the external RESTful service is bound to 6041 by default (the actual value is serverPort + 11, so it can be changed by modifying the setting of the serverPort parameter). - httpMaxThreads: the number of threads to start, default is 2 (the default value is rounded down to half of the CPU cores with version 2.0.17.0 and later versions). - restfulRowLimit: the maximum number of result sets (in JSON format) to return. The default value is 10240. - httpEnableCompress: whether to support compression, the default is not supported. Currently, TDengine only supports the gzip compression format. - httpDebugFlag: logging switch, default 131. 131: error and alarm messages only, 135: debug messages, 143: very detailed debug messages, default 131. - httpDbNameMandatory: users must specify the default database name in the RESTful URL. The default is 0, which turns off this check. If set to 1, users must put a default database name in every RESTful URL. Otherwise, it will return an execution error and reject this SQL statement, regardless of whether the SQL statement executed at this time requires a specified database. :::note If you are using the REST API provided by taosd, you should write the above configuration in taosd's configuration file taos.cfg. If you use the REST API of taosAdaper, you need to refer to taosAdaper [corresponding configuration method](/reference/taosadapter/). :::