User Interface API

These user interface API validates the requests from clients with JWT based authentication.

User Authenticate

Login

POST /web/api/login

{
    "loginName": "sys",
    "password": "manager"
}

{
    "success": true,
    "accessToken": "jwt-access-token",
    "refreshToken": "jwt-refresh-token",
    "reason": "string",
    "elapse": "string",
    "server": { "version": "v1.2.3" }
}

Refresh token

POST /web/api/relogin

{
    "refreshToken": "refresh token that was issued with 'login'"
}

{
    "success": true,
    "accessToken": "jwt access token",
    "refreshToken": "jwt refresh token",
    "reason": "string",
    "elapse": "string",
    "server": { "version": "v1.2.3" }
}

Logout

POST /web/api/logout

LogoutReq:

{
    "refreshToken": "refresh token that was issued with 'login'"
}

Status

GET /web/api/check

Validates current token status.

LoginCheckRsp

{
    "success": true,
    "reason": "string",
    "elapse": "string",
    "experimentMode": false,
    "server": {"version":"v1.2.3"},
    "shells": [{"ShellDefinition"}]
}

ShellDefinition

{
    "id": "shell definition id (uuid)",
    "type": "type",
    "icon": "icon name",
    "label": "display name",
    "theme": "theme name",
    "command": "terminal shell command",
    "attributes": [
        { "removable": true },
        { "cloneable": true },
        { "editable": true }
    ]
}

types

type	description
sql	sql editor
tql	tql editor
wrk	workspace editor
taz	tag analyzer
term	terminal

Database

Execute SQL

GET,POST /web/machbase

It works as same as /db/query API, the only difference is the way of authentication. The /db/query authorize the client applications by API Token, while /web/machbase validates JWT for user interactions.

List tables

GET /web/api/tables?showall=false&name=pattern

Return table list

showall returns includes all hidden tables if set true
name table name filtering pattern, the pattern can be a glob (includes ? or *) or prefix (which has no ? and *)

{
    "success": true,
    "reason": "success or other message",
    "elapse": "elapse time in string format",
    "data": {
        "columns": ["ROWNUM", "DB", "USER", "NAME", "TYPE"],
        "types": ["int32", "string", "string", "string", "string"],
        "rows":[
            [1, "MACHBASE", "SYS", "TABLENAME", "TAG TABLE"],
        ]
    }
}

List tags

GET /web/api/tables/:table/tags?name=prefix

Returns tag list of the table

name returns only tags those name starts with the given prefix

{
    "success": true,
    "reason": "success or other message",
    "elapse": "elapse time in string format",
    "data": {
        "columns": ["ROWNUM", "NAME"],
        "types": ["int32", "string"],
        "rows":[
            [1, "temperature"],
        ]
    }
}

Tag stat

GET /web/api/tables/:table/:tag/stat

Returns the stat of tag of the table

{
    "success": true,
    "reason": "success or other message",
    "elapse": "elapse time in string format",
    "data": {
        "columns": ["ROWNUM", "NAME", "ROW_COUNT", "MIN_TIME", "MAX_TIME",
			"MIN_VALUE", "MIN_VALUE_TIME", "MAX_VALUE", "MAX_VALUE_TIME", "RECENT_ROW_TIME"],
        "types": ["int32", "string", "int64", "datetime", "datetime","double", 
            "datetime", "double", , "datetime",, "datetime"],
        "rows":[
            ["...omit...."],
        ]
    }
}

Shell & Terminal

Data channel

ws:///web/api/term/:term_id/data

Web socket for terminal

Window size

POST /web/api/term/:term_id/windowsize

Change terminal size

TerminalSize

{ "rows": 24, "cols": 80 }

Get Shell Definition

GET /web/api/shell/:id

Returns ShellDefinition for the given id

Update Shell Definition

POST /web/api/shell/:id

Update the ShellDefinition of the given id

Make copy of Shell

GET /web/api/shell/:id/copy

Returns ShellDefinition for a new copy of the shell of the given id

Delete Shell Definition

DELETE /web/api/shell/:id

Delete the shell of the given id

{
    "success": true,
    "reason": "success of error message",
    "elapse": "time represents in text"
}

Server events

Event channel

ws:/web/api/console/:console_id/data

Web socket for the bi-directional messages

message type

{
    "type": "type(see below)",
    "ping": {
        "tick": 1234
    },
    "log": {
        "level": "INFO",
        "message": "log message"
    }
}

type	fields	description
`ping`		ping message
	`ping.tick`	any integer number, server will respond with the same number that client sends
`log`	`log.level`	log level `TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR`
	`log.message`	log message
	`log.repeat`	count, if the same message repeats more than two times in serial

TQL & Workspace

Content-types of TQL

Header `Content-Type`	Header `X-Chart-Type`	Content
text/html	“echart”	Full HTML (echart) ex) It may be inside of `<iframe>`
text/html	-	Full HTML ex) It may be inside of `<iframe>`
text/csv	-	CSV
text/markdown	-	Markdown
application/json	“echart”	JSON (echart data)
application/json	-	JSON
application/xhtml+xml	-	HTML Element, ex) `<div>...</div>`

Run tql file

GET /web/api/tql/*path

Run the tql of the path, refer the section of ‘Content-types of TQL’ for the response

POST /web/api/tql/*path

Run the tql of the path, refer the section of ‘Content-types of TQL’ for the response

Run tql script

POST /web/api/tql

Post tql script as content payload, server will response the execution result. refer the section of ‘Content-types of TQL’ for the response.

If the request has a $ named query parameter, it will be taken as the tql script, and the payload will be treated as data. This $ query parameter is available since v8.0.17.

Markdown rendering

POST /web/api/md

Post markdown as content payload, sever will response the rendering result in xhtml

File management

Content-Type

File types and content-type

file type	Content-Type
.sql	text/plain
.tql	text/plain
.taz	application/json
.wrk	application/json
unknown	application/octet-stream

Read file

GET /web/api/files/*path

Returns the content of the file if the path is pointing a file.

Returns Dir entries if the path is pointing a directory.

Entry

{
    "isDir": true,
    "name": "name",
    "content": "bytes array, if the entry is a file",
    "children": [{"SubEntry, if the entry is a directory"}],
}

SubEntry

{
    "isDir": true,
    "name": "name",
    "type": "type",
    "size": 1234,
    "lastModifiedUnixMillis": 169384757
}

Write file

POST /web/api/files/*path

if the path points a file, it will write the payload content into the file.
if the path is a directory and request with no content, it will create a empty directory. and returns the Entry of the directory
if the path is a directory and payload is json of GitCloneReq, it will clone the remote git repository to the path and returns Entry of the directory.

GitCloneReq

{
    "command": "clone",
    "url": "https://github.com/machbase/neo-samples.git"
}

command : clone, pull

Rename/move file

PUT /web/api/files/*path

Rename(move) a file (or a directory).

RenameReq

{
    "destination": "target path",
}

This api returns status code 200 OK if the operation has done successfully.

Remove file

DELETE /web/api/files/*path

Delete the file at the path, if the path is pointing a directory and is not empty, it will return error.

Key management

List Key

GET /web/api/keys/:id

Return key info list

response

{
    "success": true,
    "reason": "success",
    "data": [
        {
            "idx": 0,
            "id": "eleven",
            "notBefore": 1713171461,
            "notAfter": 2028531461
        }
    ],
    "elapse": "131.9µs"
}

Generate Key

POST /web/api/keys

generate key

name is required
notAfter is expiration date

{
    "name": "eleven",
    "notBefore": 0,
    "notAfter": 0
}

{
    "success": true,
    "reason": "success",
    "elapse": "5.4961ms",
    "certificate": "-----BEGIN CERTIFICATE-----\nXXXXXXXXXXXXXXXXXX\n-----END CERTIFICATE-----\n",
    "privateKey": "-----BEGIN EC PRIVATE KEY-----\nXXXXXXXXXXXXXXXX\n-----END EC PRIVATE KEY-----\n",
    "token": "eleven:b:XXXXXXXXXXXXXXXXX"
}

Delete Key

DELETE /web/api/keys/:id

Delete the key of the given id

response

{
    "success": true,
    "reason": "success",
    "elapse": "112.8µs"
}

Timer

List Timer

GET /web/api/timers

Return timer info list

response

{
    "success": true,
    "reason": "success",
    "data": [
        {
            "name": "ELEVEN",
            "type": "TIMER",
            "state": "STOP",
            "task": "timer.tql",
            "schedule": "0 30 * * * *"
        }
    ],
    "elapse": "92.1µs"
}

Add Timer

POST /web/api/timers

Add Timer

name, autoStart, schedule, path is required

Timer schedule

0 30 * * * * Every hour on the half hour
@every 1h30m Every hour thirty
@daily Every day

{
    "name":"eleven",
    "autoStart":false,
    "schedule":"@every 10s",
    "path":"timer.tql"
}

{
    "success": true,
    "reason": "success",
    "elapse": "4.9658ms"
}

Start Timer

POST /web/api/timers/:name/state

Start Timer

state is required

{
    "state":"start",
}

{
    "success": true,
    "reason": "success",
    "elapse": "822.601µs"
}

Stop Timer

POST /web/api/timers/:name/state

Stop Timer

state is required

{
    "state":"stop",
}

{
    "success": true,
    "reason": "success",
    "elapse": "26.2µs"
}

Update Timer

PUT /web/api/timers/:name

Update Timer

autoStart, schedule, path

{
    "audoStart" : true,
    "schedule":"@every 5s",
    "path":"timer.tql"
}

{
    "elapse": "459.6µs",
    "reason": "success",
    "success": true
}

Delete Timer

DELETE /web/api/timers/:name

Delete Timer

Response

{
    "success": true,
    "reason": "success",
    "elapse": "4.8664ms"
}

Bridge

List Bridge

GET /web/api/bridges

Return bridge info list

response

{
    "success": true,
    "reason": "success",
    "data": [
        {
            "name": "pg",
            "type": "postgres",
            "path": "host=127.0.0.1 port=5432 user=postgres password=1234 dbname=bridgedb sslmode=disable"
        }
    ],
    "elapse": "1.328301ms"
}

Add Bridge

POST /web/api/bridges

Add Bridge

name, type, path is required
supported bridges SQLite, PostgreSql, Mysql, MSSQL, MQTT

{
    "name":"pg",
    "type":"postgres", // sqlite, postgres, mysql, mssql, mqtt
    "path":"host=127.0.0.1 port=5432 user=postgres password=1234 dbname=bridgedb sslmode=disable"
}

{
    "success": true,
    "reason": "success",
    "elapse": "193.499µs"
}

Exec Bridge

POST /web/api/bridges/:name/state

Exec Bridge

state, command is required

{
    "state":"exec",
    "command":"CREATE TABLE IF NOT EXISTS pg_example(id SERIAL PRIMARY KEY,company VARCHAR(50) UNIQUE NOT NULL,employee  INT,discount REAL,plan FLOAT(8),code UUID,valid BOOL, memo TEXT, created_on TIMESTAMP NOT NULL)"
}

{
    "success": true,
    "reason": "success",
    "elapse": "217.4µs"
}

Query Bridge

POST /web/api/bridges/:name/state

Query Bridge

state, command is required

{
    "state":"query",
    "command":"select * from pg_example"
}

{
    "success": true,
    "reason": "success",
    "column": [
        "id",
        "company",
        "employee",
        "discount",
        "plan",
        "code",
        "valid",
        "memo",
        "created_on"
    ],
    "rows": [
        [
            2,
            "test-company",
            10,
            1.234,
            2.3456,
            "c2d29867-3d0b-d497-9191-18a9d8ee7830",
            true,
            "test memo",
            "2023-08-09T14:20:00+09:00"
        ],
        [
            3,
            "test-company2",
            10,
            1.234,
            2.3456,
            null,
            null,
            null,
            "2023-08-09T14:20:00+09:00"
        ]
    ],
    "elapse": "53.015905ms"
}

Test Bridge

POST /web/api/bridges/:name/state

Test Bridge

{
    "state":"test",
}

{
    "success": true,
    "reason": "success",
    "elapse": "331.1µs"
}

Delete Bridge

DELETE /web/api/bridges/:name

Delete the bridge of the given name

response

{
    "success": true,
    "reason": "success",
    "elapse": "112.8µs"
}

Others

References

GET /web/api/refs/*path

ReferenceGroup

{
    "label": "group name",
    "items":[{"ReferenceItem"}]
}

ReferenceItem

{
    "type": "type",
    "title": "display title",
    "address": "url address",
    "target": "browser link target"
}

type: url, wrk, tql, sql
address: if address has prefix serverfile://<path> it points a server side file, otherwise external web url that starts with https://

License info

GET /web/api/license

{
    "success": true,
    "reason": "success or error reason",
    "elapse": "elapse time",
    "data": {
        "id": "license id",
        "type": "type",
        "customer": "customer",
        "project": "project",
        "countryCode": "country code",
        "installDate": "installation date",
        "issueDate": "license issue date"
    }
}

License install

POST /web/api/license

Install license file

Last updated on Jun 4, 2024

ILP line protocol Client in JavaScript