Connect to KWDB Using RESTful API

The KWDB RESTful API enables interaction with KWDB databases through HTTP requests. It provides the following capabilities:

Authenticate users and manage sessions
Execute DDL operations (create/drop tables, databases, etc.)
Insert data
Query data
Support for third-party data formats (Telegraf, InfluxDB, OpenTSDB)
Manage user sessions

All API requests use HTTPS and must include authentication information. The API supports up to 150 simultaneous HTTP connections.

The format of the HTTP request URL is:

https://<hostname>:<port>/<endpoint>?[tz=<timezone>][db=<db_name>]

Parameter descriptions:

hostname: The IP address or fully qualified domain name (FQDN) of the KWDB server.
port: The HTTP access port of the KWDB server (default: 8080).
tz: Specifies the timezone for the request. If provided, this timezone is used; otherwise, the system uses the value from the cluster parameter server.restful_service.default_request_timezone. Timezone information in the data itself takes precedence when present.
db_name: (Optional) Specifies the target database. KWDB encloses the database name in double quotes ("") to handle case sensitivity and special characters. If not specified, the system uses the default database (defaultdb). The Login endpoint does not support this parameter.

API Endpoints

WARNING

RESTful API endpoints currently support interaction with a single node only.

KWDB provides the following RESTful API endpoints:

Endpoint	Description	Path
Login	Authenticates users and provides authentication tokens	`GET /restapi/login`
DDL	Processes Data Definition Language operations	`POST /restapi/ddl`
Insert	Handles data insertion operations	`POST /restapi/insert`
Query	Processes data query operations	`POST /restapi/query`
Telegraf	Handles data insertion from Telegraf	`POST /restapi/telegraf`
InfluxDB	Handles data insertion from InfluxDB	`POST /restapi/influxdb`
OpenTSDB JSON	Handles data insertion in OpenTSDB JSON format	`POST /restapi/opentsdbjson`
OpenTSDB Telnet	Handles data insertion in OpenTSDB Telnet format	`POST /restapi/opentsdbtelnet`
Session	Manages sessions; allows viewing or deleting sessions based on user privileges	`GET /restapi/session` `DELETE /restapi/session`

The Login endpoint authenticates users and provides tokens for subsequent API calls. Based on the provided Base64-encoded username and password, the system generates a token with a configurable validity period.

Note

Each login or token usage refreshes the token's start time and expiration time.
The default token validity period is 60 minutes, configurable using the SQL statement SET CLUSTER SETTING server.rest.timeout=<value> (range: [1, 2^63-1] minutes).
When implementing concurrent RESTful API requests, assign a separate token for each thread to ensure reliable operation (concurrency limit: 100).
KWDB also supports direct authentication using Base64-encoded username and password in the HTTP request header, see Authentication Methods for differences.

Request Information

Item	Content	Description
Endpoint	- Without timezone: `/restapi/login` - With timezone:`/restapi/login?tz="timezone"`	-
Method	`GET`	-
Request Header	`Content-Type: text/plain Accept: application/json Authorization: Basic "base64(user:password)"`	`base64(user:password)`: Base64-encoded username and password.
Request Body	Empty	-

Response Information

Item Content Description

HTTP Status Code HTTP/1.1 "code" "desc" - code(int): HTTP status code.
- desc(string): Status description. For details, see HTTP Status Codes.

Response Header

Item	Content	Description
HTTP Status Code	`HTTP/1.1 "code" "desc"`	- `code(int)`: HTTP status code. - `desc(string)`: Status description. For details, see HTTP Status Codes.
Response Header	`Content-Type: application/json Accept: text/plain`	-
Response Body	- Success `{ "code": "code", "token": "token" }` - Failure `{ "code": "code", "desc": "desc", }`	- `code(int)`: HTTP status code. (0 = success, -1 = failure). - `token(string)`: Token generated from credentials. - `desc (string)`: Error description (for failures only).

Content-Type: application/json
Accept: text/plain

Response Body

- Success

{
"code": "code",
"token": "token"
}

- Failure

{
  "code": "code",
  "desc": "desc",
}

- code(int): HTTP status code. (0 = success, -1 = failure).
- token(string): Token generated from credentials.
- desc (string): Error description (for failures only).

Configuration Example

The following example sends an HTTP request to obtain an authentication token:

GET /restapi/login HTTP/1.1
Host: localhost:8080
Content-Type: plain/text
Accept: application/json
Authorization: dTE6a3dkYnBhc3N3b3Jk

Successful response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "code": 0,
  "token": "cm9vdDprd2RicGFzc3dvcmQ="
}

Failed response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "code": -1,
  "desc": "the provided username and password did not match any credentials on the server"
}

DDL Endpoint

The DDL endpoint processes HTTP requests containing Data Definition Language (DDL) statements. Users must have permissions for the specific DDL operations they intend to perform.

KWDB supports the following DDL operations through this endpoint:

CREATE
DROP
DELETE
USE
ALTER
UPDATE
GRANT
REVOKE

Request Information

Item	Content	Description
Endpoint	- Without timezone: `/restapi/ddl` - With timezone: `/restapi/ddl?tz="timezone"`	-
Method	`POST`	-
Request Header	`Content-Type: text/plain Accept: application/json Authorization: Basic "token" or Basic "base64(user:password)"`	- `token(string)`: Token generated from credentials. - `base64(user:password)`: Base64-encoded username and password.
Request Body	`"sql"`	`sql(string)`: SQL statement(s) to execute. Multiple statements must be separated by semicolons (`;`).

Response Information

Item Content Description

HTTP Status Code HTTP/1.1 "code" "desc" - code(int): HTTP Status Code.
- desc(string): Status description. For details, see HTTP Status Codes.

Response Header

Content-Type: application/json
Accept: text/plain

Response Body

- Success

{
"code": "code",
"time": "time"
}

- Failure

{
  "code": "code",
  "desc": "desc1", "desc2", ...,
}

- code(int): Execution status (0 = all statements succeeded, -1 = at least one statement failed)
- desc(string): Array of execution results, one per statement ("success" or error message)
- time(float): Execution time in seconds

Configuration Example

The following example sends an HTTP request to create a table named meters:

POST /restapi/ddl HTTP/1.1
Host: localhost:8080
Authorization: Basic cm9vdDprd2RicGFzc3dvcmQ=
Content-Type: plain/text
Accept: application/json

CREATE TABLE meters (ts timestamp not null, power int) tags(location varchar not null) primary tags (location); CREATE TABLE wind (ts timestamp not null, speed int) tags(location varchar not null) primary tags (location);

Successful response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "code": 0,
  "desc": [
      "success",
      "success"
  ],
  "time": 0.002
}

Insert Endpoint

The Insert endpoint processes HTTP requests containing INSERT statements. It supports data insertion requests, including those from EMQX. Users must have INSERT privileges on the target table to use this endpoint.

Request Information

Item	Content	Description
Endpoint	- Without timezone: `/restapi/insert` - With timezone: `/restapi/insert?tz="timezone"`	-
Method	`POST`	-
Request Header	`Content-Type: text/plain Accept: application/json Authorization: Basic "token" or Basic "base64(user:password)"`	- `token(string)`: Token generated from credentials. - `base64(user:password)`: Base64-encoded username and password.
Request Body	`"sql"`	`sql(string)`: SQL statement(s) to execute. Multiple statements must be separated by semicolons(`;`).

Response Information

Item	Content	Description
HTTP Status Code	`HTTP/1.1 "code" "desc"`	- `code(int)`: HTTP Status Code. - `desc(string)`: Status description. For details, see HTTP Status Codes.
Response Header	`Content-Type: application/json Accept: text/plain`	-
Response Body	`{ "code": "code", "desc": "desc1","desc2" ... "descN", "rows": "string", "notice": "string", "time": "time" }`	- `code(int)`: Execution status (0 = all statements succeeded, -1 = at least one statement failed) - `desc(string)`: Array of execution results, one per statement ("success" or error message) - `rows(string)`: Number of rows inserted (null if operation failed) - `notice(string)`: Failed insertion details (null if all operations succeeded) - `time(float)`: Execution time in seconds

Configuration Example

The following example sends an HTTP request to insert data to the meters table:

POST /restapi/insert HTTP/1.1
Host: localhost:8080
Authorization: Basic cm9vdDprd2RicGFzc3dvcmQ=
Content-Type: plain/text

insert into meters values("2023-07-30T06:44:40.32Z", "198352498", "beijing");insert into meters values("2023-07-30T06:45:40.32Z", "198352495", "beijing");

Successful response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "code": 0,
  "desc": [
    "success",
    "success"
  ],
  "rows": 1,
  "notice": null
  "time": 0.002
}

Failed response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "code": -1,
  "desc": [
    "Incorrect authentication token",
    "Incorrect authentication token"
  ],
  "rows": null,
  "notice": null
  "time": null
}

Query Endpoint

The Query endpoint processes HTTP requests for data retrieval. Users must have SELECT privileges for the queried tables. Currently, this endpoint supports SELECT, SHOW CREATE TABLE, and SHOW statements.

Request Information

Item	Content	Description
Endpoint	- Without timezone: `/restapi/query` - With timezone: `/restapi/query?tz="timezone"`	-
Method	`POST`	-
Request Header	`Content-Type: text/plain Accept: application/json Authorization: Basic "token" or Basic "base64(user:password)"`	- `token(string)`: Token generated from credentials. - `base64(user:password)`: Base64-encoded username and password.
Request Body	`"sql"`	`sql(string)`: SQL statement(s) to execute. Multiple statements must be separated by semicolons (`;`).

Response Information

Note

To prevent performance issues, response body size is limited to 5 MB. Data exceeding this limit will be truncated.

Item	Content	Description
HTTP Status Code	`HTTP/1.1 "code" "desc"`	- `code(int)`: HTTP Status Code. - `desc(string)`: Status description. For details, see HTTP Status Codes.
Response Header	`Content-Type: application/json Accept: text/plain`	-
Response Body	`{ "code": "code", "desc": "desc", "time": "time", "column_meta": "column_meta", "data": "data", "rows": "rows" }`	- `code(int)`: Status code (0 = success, other values = failure) - `desc(string)`: Error description (null or error messages) - `time(float)`: Execution time in seconds - `column_meta(array)`: Array of column metadata in format [column_name, data_type, type_length] - `data(array)`: Array of query result rows - `rows(int)`: Number of rows returned

Configuration Example

The following example sends an HTTP request to query the data in table ts_table.

POST /restapi/query HTTP/1.1
Host: localhost:8080
Authorization: Basic cm9vdDprd2RicGFzc3dvcmQ=
Content-Type: plain/text

select * from ts_table;

Successful response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "code": 0,
  "desc": null,
  "time": 0.022829285,
  "column_meta": [
      [
          "ts",
          "TIMESTAMP",
          8
      ],
      [
          "id",
          "VARCHAR",
          128
      ],
      [
          "electricity",
          "FLOAT",
          8
      ]
  ],
  "data": [
      [
          "2023-07-30T06:44:40.32Z",
          "198352498",
          0.31
      ],
      [
          "2023-07-30T06:44:41.32Z",
          "234758890",
          0.33
      ]
  ],
  "rows": 2
}

Failed response:

HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
  "code": 500,
  "desc": "No table named ts_table found",
  "time": null，
  "column_meta": null,
  "data": null,
  "rows": null
}

Telegraf Endpoint

The Telegraf endpoint accepts data in InfluxDB Line format from Telegraf collectors. Users must have INSERT privileges on the target tables to use this endpoint.

Before using this endpoint, you need to create the corresponding time-series tables in KWDB based on the Telegraf data structure. KWDB will convert the InfluxDB Line format data into SQL statements for insertion.

The data format used by the Telegraf endpoint is:

<measurement>,<tag_set> <field_set> <timestamp>

Parameter Descriptions:

measurement: Required. Specifies the time-series table name in KWDB. KWDB uses this field to determine whether to create a new table or insert data into an existing one. The table name is enclosed in double quotes ("") to handle case sensitivity and names starting with special characters or digits. If the specified table does not exist, it will be created first, then data is written. A comma (,) separates measurement and tag_set.
tag_set: Optional. Format: <tag_key>=<tag_value>,<tag_key>=<tag_value>, .... Specifies tag names and values for the time-series table. Tags are separated by commas. KWDB determines which tag to write and whether to add new tags based on the tag_key. Tag names are enclosed in double quotes ("") to handle case sensitivity and names starting with special characters or digits. Missing tags are added automatically; unspecified tags will be set to NULL. KWDB will also generate a primary_tag column with corresponding values, using VARCHAR type. A comma (,) separates tag_set and field_set.
field_set: Required. Format: <field_key>=<field_value>,<field_key>=<field_value>, .... Specifies data field names and values. Fields are separated by commas. KWDB determines which column to write to and whether to add new columns based on the field_key. Column names are enclosed in double quotes (""). Missing columns are added automatically; unspecified fields will be set to NULL. A space separates the field_set and timestamp.
timestamp: Optional. Specifies the timestamp of the record. If omitted, KWDB uses the host's system time in UTC. Millisecond, microsecond, and nanosecond precisions are supported, with nanosecond as the default.

Example of converting InfluxDB Line protocol data to KWDB SQL statements:

InfluxDB data

meters,location=Beijing current=17.01,voltage=220,phase=0.29 1556813561098000000

Converted KWDB SQL statements

create table meters (ts timestamp not null, current float, voltage int, phase float) tags (location varchar(20) not null) primary tags (location);

For more information on InfluxDB Line protocol, see InfluxDB Official Documentationopen in new window.

Request Information

Item	Content	Description
Endpoint	`/restapi/telegraf`	-
Method	`POST`	-
Request Header	`Content-Type: text/plain Accept: application/json Authorization: Basic "token" or Basic "base64(user:password)"`	- `token(string)`: Token generated from credentials. - `base64(user:password)`: Base64-encoded username and password.
Request Body	`"line_format"`	`line_format(string)`: The InfluxDB Line format data to be inserted.

Response Information

Item	Content	Description
HTTP Status Code	`HTTP/1.1 "code" "desc"`	- `code(int)`: HTTP Status Code. - `desc(string)`: Status description. For details, see HTTP Status Codes.
Response Header	`Content-Type: application/json Accept: text/plain`	-
Response Body	`{ "code": "code", "desc": "desc", "rows": "rows", "time": "time" }`	- `code(int)`: Execution status (0 = all operations succeeded, -1 = at least one operation failed) - `desc(string)`: Error description (null for successful operations) - `rows(int)`: Number of rows inserted - `time(float)`: Execution time in seconds

Configuration Example

The following example sends an HTTP request to insert data into the myMeasurement table.

POST /restapi/telegraf HTTP/1.1
Host: localhost:8080
Authorization: Basic cm9vdDprd2RicGFzc3dvcmQ=
Content-Type: plain/text

myMeasurement,tag1=value1,tag2=value2 fieldKey="fieldValue" 1556813561098000000

Successful response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "code": 0,
  "desc": null,
  "rows": 1,
  "time": 0.002
}

Failed response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "code": 500,
  "desc": "Incorrect authentication token",
  "rows": null,
  "time": null
}

InfluxDB Endpoint

The InfluxDB endpoint accepts data in InfluxDB Line Protocol format. Users must have appropriate privileges to execute the generated SQL statements. Unlike the Telegraf endpoint, you only need to create the time-series database before using this endpoint; KWDB will automatically handle table creation, column addition, and data insertion as needed.

Request Information

Item	Content	Description
Endpoint	- Without timezone: `/restapi/influxdb` - With timezone: `/restapi/influxdb?tz="timezone"`	-
Method	`POST`	-
Request Header	`Content-Type: text/plain Accept: application/json Authorization: Basic "token" or Basic "base64(user:password)"`	- `token(string)`: Token generated from credentials. - `base64(user:password)`: Base64-encoded username and password.
Request Body	`"line_format"`	`line_format(string)`: One or more lines of data in InfluxDB Line format.

Response Information

Item	Content	Description
HTTP Status Code	`HTTP/1.1 "code" "desc"`	- `code(int)`: HTTP Status Code. - `desc(string)`: Status description. For details, see HTTP Status Codes.
Response Header	`Content-Type: application/json Accept: text/plain`	-
Response Body	`{ "code": "code", "desc": "desc", "rows": "rows", "time": "time" }`	- `code(int)`: Execution status (0 = all operations succeeded, -1 = at least one operation failed) - `desc(string)`: Error description (null for successful operations) - `rows(stringint)`: Number of rows inserted - `time(float)`: Execution time in seconds

Configuration Example

The following table sends an HTTP request to create the table myMeasurement or insert data into the myMeasurement table.

POST /restapi/influxdb HTTP/1.1
Host: localhost:8080
Authorization: Basic cm9vdDprd2RicGFzc3dvcmQ=
Content-Type: plain/text

myMeasurement,tag1=value1,tag2=value2 fieldKey="fieldValue" 1556813561098000000

Successful response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "code": 0,
  "desc": null,
  "rows": 1,
  "time": 0.002
}

Failed response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "code": -1,
  "desc": "Incorrect authentication token",
  "rows": null,
  "time": null
}

OpenTSDB JSON Endpoint

The OpenTSDB JSON endpoint accepts data in OpenTSDB JSON format. Users must have appropriate privileges to execute the generated SQL statements. You only need to create the time-series database before using this endpoint; KWDB will automatically handle table creation, column addition, and data insertion as needed.

Request Information

Item	Content	Description
Endpoint	- Without timezone: `/restapi/opentsdbjson` - With timezone: `/restapi/opentsdbjson?tz="timezone"`	-
Method	`POST`	-
Request Header	`Content-Type: text/plain Accept: application/json Authorization: Basic "token" or Basic "base64(user:password)"`	- `token(string)`: Token generated from credentials. - `base64(user:password)`: Base64-encoded username and password.
Request Body	`"line_format"`	`line_format(string)`: One or more lines of data in the OpenTSDB JSON format.

Response Information

Item	Content	Description
HTTP Status Code	`HTTP/1.1 "code" "desc"`	- `code(int)`: HTTP Status Code. - `desc(string)`: Status description. For details, see HTTP Status Codes.
Response Header	`Content-Type: application/json Accept: text/plain`	-
Response Body	`{ "code": "code", "desc": "desc", "rows": "rows", "time": "time" }`	- `code(int)`: Execution status (0 = all operations succeeded, -1 = at least one operation failed) - `desc(string)`: Error description (null for successful operations) - `rows(stringint)`: Number of rows inserted - `time(float)`: Execution time in seconds

Configuration Example

The following example sends an HTTP request to create the sys.cpu.usage table or insert data into the sys.cpu.usage table.

POST /restapi/opentsdbjson HTTP/1.1
Host: localhost:8081
Content-Type: text/plain
Authorization: Basic *******


[{"metric": "sys.cpu.usage","timestamp": 1654567205,"value": 0.5,"tags": {"host": "server1","dc": "1"}},{"metric": "sys.cpu.usage","timestamp": 1654567205,"value": 0.7,"tags": {"host": "server1","dc2": "us-west"}}]

Successful response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "code":0,
  "desc":"success;success;",
  "time":0.088146837,
  "rows":2
}

Failed response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "code": -1,
  "desc": "Incorrect authentication token",
  "rows": null,
  "time": null
}

OpenTSDB Telnet Endpoint

The OpenTSDB Telnet endpoint accepts data in OpenTSDB Telnet format. Users must have appropriate privileges to execute the generated SQL statements. You only need to create the time-series database before using this endpoint; KWDB will automatically handle table creation, column addition, and data insertion as needed.

Request Information

Item	Content	Description
Endpoint	- Without timezone: `/restapi/opentsdbtelnet` - With timezone: `/restapi/opentsdbtelnet?tz="timezone"`	-
Method	`POST`	-
Request Header	`Content-Type: text/plain Accept: application/json Authorization: Basic "token" or Basic "base64(user:password)"`	- `token(string)`: Token generated from credentials. - `base64(user:password)`: Base64-encoded username and password.
Request Body	`"line_format"`	`line_format(string)`: One or more lines of data in the OpenTSDB Telnet format.

Response Information

Item	Content	Description
HTTP Status Code	`HTTP/1.1 "code" "desc"`	- `code(int)`: HTTP Status Code. - `desc(string)`: Status description. For details, see HTTP Status Codes.
Response Header	`Content-Type: application/json Accept: text/plain`	-
Response Body	`{ "code": "code", "desc": "desc", "rows": "rows", "time": "time" }`	- `code(int)`: Execution status (0 = all operations succeeded, -1 = at least one operation failed) - `desc(string)`: Error description (null for successful operations) - `rows(stringint)`: Number of rows inserted - `time(float)`: Execution time in seconds

Configuration Example

The following example sends an HTTP request to create the meters table or insert data into the meters table.

POST /restapi/opentsdbtelnet HTTP/1.1
Host: localhost:8081
Content-Type: text/plain
Authorization: Basic *******


meters.current 1648432611250 11.3 location=California.LosAngeles groupid=3 extraTag=value

Successful response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "code":0,
  "desc":"success;",
  "time":1.279927072,
  "rows":1
}

Failed response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "code": -1,
  "desc": "Incorrect authentication token",
  "rows": null,
  "time": null
}

Session Endpoint

The Session endpointallows users to query session information and delete specified sessions. Administrators can view all session information and delete any session, while regular users can only view and delete their own sessions.

Request Information

Item	Content	Description
Endpoint	- Without timezone: `/restapi/session` - With timezone: `/restapi/session?tz="timezone"`	-
Method	- View sessions: `GET` - Delete sessions: `DELETE`	-
Request Header	`Content-Type: text/plain Accept: application/json Authorization: Basic "token" or Basic "base64(user:password)"`	- `token(string)`: Token generated from credentials. - `base64(user:password)`: Base64-encoded username and password.
Request Body	- View sessions: Empty - Delete sessions: `"conn_id"`	`"conn_id"`: The SessionID of the session to be deleted, required only when deleting a specific session.

Response Information

Viewing Sessions

Item	Content	Description
HTTP Status Code	`HTTP/1.1 "code" "desc"`	- `code(int)`: HTTP Status Code. - `desc(string)`: Status description. For details, see HTTP Status Codes.
Response Header	`Content-Type: application/json Accept: text/plain`	-
Response Body	`{ "code": "code", "tokens": [{"session_info"}] }`	- `code(int)`: Status code. `0` indicates success, other values indicate failure. - `conn_info`: Session connection-related information, such as connection ID, username, token and timeout.

Deleting Sessions

Item	Content	Description
HTTP Status Code	`HTTP/1.1 "code" "desc"`	- `code(int)`: HTTP Status Code. - `desc(string)`: Status description. For details, see HTTP Status Codes.
Response Header	`Content-Type: application/json Accept: text/plain`	-
Response Body	`{ "code": "code", "desc": "desc" }`	- `code(int)`: Status code(0 = success, other values = failure). - `desc(string)`: Description of the delete operation result.

Configuration Example

Example 1: Viewing session information

Request:

GET /restapi/session HTTP/1.1
Content-Type: text/plain
Accept: application/json
Authorization: Basic cm9vdDprd2RicGFzc3dvcmQ=

Successful response:

Regular users (view their own session only):

{
"code":0,
"tokens":[{"SessionID":"1970e371-5947-11ef-8726-000c29585cae","Username":"u1","Token":"9c7e0ad44a9e02dc67fb2f3e48446769","MaxLifeTime":3600,"LastLoginTime":"2024-08-13 07:41:08","ExpirationTime":"2024-08-13 08:41:08"}]
}

Administrators (view all sessions):

{"code":0,
"tokens":[
{"SessionID":"50830553-3e83-11ef-a323-b4055d17f786","Username":"u1","Token":"c2ff2c6d*","MaxLife Time":3600,"LastLoginTime":"2024-07-10 06:11:58","ExpirationTime":"2024-07-10 07:11:58"},
{"SessionID":"9bf2fa13-3e83-11ef-a323-b4055d17f786","Username":"u1","Token":"f9f3a39d*","MaxLife Time":3600,"LastLoginTime":"2024-07-10 06:14:04","ExpirationTime":"2024-07-10 07:14:04"}
]
}

Example 2: Deleting a session

Request:

DELETE /restapi/session HTTP/1.1
Content-Type: text/plain
Accept: application/json
Authorization: Basic cm9vdDprd2RicGFzc3dvcmQ=

0339f5b5-c492-11ee-a7c9-000c29066670

Successful response:

{
  "code":0,
  "desc": "Delete Success"
}

Authentication Methods

All KWDB RESTful API requests are sent using HTTPS and All KWDB RESTful API requests use HTTPS and are authenticated through the HTTP Header.

The following authentication methods are supported:

Username and Password Authentication

Users include a Base64-encoded database username and password in the HTTP request header. Upon successful authentication, the system creates a temporary token for identity verification that is automatically destroyed after the request completes. This method is simple to implement with no connection limits but requires higher system performance, making it suitable for scenarios with small data volumes and low performance requirements.

Token Authentication

Users first obtain a token by calling the RESTful API login interface. This token can then be used for authentication in subsequent API calls, such as the DDL endpoint and the Insert endpoint.

Token Configuration:

Tokens are valid for 60 minutes by default
Adjust token validity using SET CLUSTER SETTING server.rest.timeout=<minutes>;
Validity can be set between 1 minute and 2^63-1 minutes
System supports up to 100 concurrent token-based connections

Token authentication eliminates the need to create and destroy temporary tokens with each request, making it more suitable for high-performance scenarios.

When implementing concurrent requests using the RESTful API, assign a unique token to each thread to ensure smooth operation.

Secure Communication with KWDB

HTTPS uses SSL encryption for data transmission. When communicating securely with the KWDB database, the KWDB server-generated certificate must be accessible by the client making the request. See Example 3 for the operation procedure.

Example 1: Using Username and Password for Authentication

<!--Request-->
POST /restapi/ddl HTTP/1.1
Host: localhost:8080
Authorization: Basic dTE6a3dkYnBhc3N3b3Jk
Content-Type: plain/text
Accept: application/json

CREATE TABLE ts_table(ts timestamp not null, power int) tags(location varchar(15) not null) primary tags (location);

Example 2: Using Token for Authentication

<!--Request-->
POST /restapi/ddl HTTP/1.1
Host: localhost:8080
Authorization: Basic cm9vdDprd2RicGFzc3dvcmQ=
Content-Type: plain/text
Accept: application/json

CREATE TABLE ts_table(ts timestamp not null, power int) tags(location varchar(15));

Example 3: Secure Communication with KWDB

Deploy and start the database in secure mode.

Create a new user in the database:

create user rest_user password 'user123456';

Copy the KWDB server-generated certificate to a path accessible by the client. The default certificate location is /etc/kaiwudb/cert.

Use the secure certificate for Restful API connections.

curl -L --cacert ../certs/ca.crt -H "Authorization: Basic dTE6a3dkYnBhc3N3b3Jk" -X GET your-host-ip:port/restapi/login

Query Example

curl -L -H "Content-Type:text/plain" -H "Authorization: Basic dTE6a3dkYnBhc3N3b3Jk"  --cacert ../certs/ca.crt -d "select*from t1;" -X POST your-host-ip:port/restapi/query?db=db1

HTTP Status Codes

After each HTTP request completes, the system returns an HTTP status code. The following table lists the HTTP status codes used by the KWDB RESTful API:

HTTP Status Code	Description
200	Success
400	Parameter Error
401	Authentication Failed
404	URL Not Found
500	Internal Error
503	Insufficient System Resources

# Connect to KWDB Using RESTful API

# API Endpoints

# Login Endpoint

# Request Information

# Response Information

# Configuration Example

# DDL Endpoint

# Request Information

# Response Information

# Configuration Example

# Insert Endpoint

# Request Information

# Response Information

# Configuration Example

# Query Endpoint

# Request Information

# Response Information

# Configuration Example

# Telegraf Endpoint

# Request Information

# Response Information

# Configuration Example

# InfluxDB Endpoint

# Request Information

# Response Information

# Configuration Example

# OpenTSDB JSON Endpoint

# Request Information

# Response Information

# Configuration Example

# OpenTSDB Telnet Endpoint

# Request Information

# Response Information

# Configuration Example

# Session Endpoint

# Request Information

# Response Information

# Configuration Example

# Authentication Methods

# HTTP Status Codes

Connect to KWDB Using RESTful API

API Endpoints

Login Endpoint

Request Information

Response Information

Configuration Example

DDL Endpoint

Request Information

Response Information

Configuration Example

Insert Endpoint

Request Information

Response Information

Configuration Example

Query Endpoint

Request Information

Response Information

Configuration Example

Telegraf Endpoint

Request Information

Response Information

Configuration Example

InfluxDB Endpoint

Request Information

Response Information

Configuration Example

OpenTSDB JSON Endpoint

Request Information

Response Information

Configuration Example

OpenTSDB Telnet Endpoint

Request Information

Response Information

Configuration Example

Session Endpoint

Request Information

Response Information

Configuration Example

Authentication Methods

HTTP Status Codes