RESTful API Overview

Representational State Transfer (REST) ​​is a type of software architecture style that consists of guidelines and best practices for interfaces provided by scalable Web services.

The four methods defined in the HTTP protocol define the CRUD for the resource.

HTTP Method










Machbase is not a standard RESTful API, but rather a RESTful API that handles CRUD using only POST and GET methods.

That is, the POST method is used for data input and the rest is transmitted as a GET Method parameter to the SQL query so that all the operations can be performed.


If $MACHBASE_HOME/webadmin/flask/MWAserver start is used to run Machbase Web Analytics (MWA), you can access the Machbase server using the Restful API.

[mach@localhost]$ cd $MACHBASE_HOME/bin
[mach@localhost]$ MWAserver start


How To Use

The Machbase RESTful API can be used in conjunction with the MWA server configuration. When using the RESTful API, specify the server ID or Server name to use as the 's' parameter. 
ex) The following example sends the query to the server whose ID is 3 (or server name is sample_server) among the servers set in MWA and receives the result

curl -G "" --data-urlencode 'q=select * from m$sys_tables' --data 's=3'
# or
curl -G "" --data-urlencode 'q=select * from m$sys_tables' --data 's=sample_server'

If it can not find the ID or name of the specified server, it returns the following json with a 404 error.

curl -G "" --data-urlencode 'q=select * from m$sys_tables' --data 's=not_exist'
  "error": "Cannot found server."

Default URL

The default URL for the Restful API is:

http://hostname: port can be found by running the MWAserver start command to run MWA with the url to connect to the MWA. 

Data Extraction

Retrieves the data using the HTTP GET method. The return value is a json type. You can pass the query statement you want to execute using the 'q' parameter. The query below brings up a list of tables.

curl -G "" --data-urlencode 'q=select * from m$sys_tables'

Data Input

You can use the HTTP POST method to send the input value of the json type as a parameter. Below is an example of entering data into a test_table with three columns.
First, we execute a query that creates a table using the curl GET method.

curl -X GET "" --data-urlencode 'q=create table test_table(c1 short, c2 integer, c3 varchar(20))'

Enter data using the POST method using the curl command. The data input json can use four keys, and the 'name' and 'values' keys must be entered.

curl -X POST -H "Content-Type: application/json" "" -d '{"name":"test_table", "values":[[1,2,"aaa"],[3,4,"bbb"]]}'





Input table name



Input data to be input as a 2-dimensional array



Date format to be used

If data type is used


Server ID or name

Server defined in MWA

If you enter a date type, you must specify the date format. The date format must use the pattern used in Machbase. If not specified otherwise, YYYY-MM-DD is set to HH24: MI: SS mmm: uuu: nnn Machbase default format and the result value will not be returned properly if date format is not correct. When specifying date and time pattern, you should be careful of case sensitive.

curl -X GET "" --data-urlencode 'q=create table test_date(c1 datetime)'

curl -X POST -H "Content-Type: application/json" "" -d '{"name":"test_date",  "date_format":"YYYY-MM-DD HH24:MI:SS", "values":[["2015-02-01 12:13:14"],["2015-02-11 07:08:09"]]}'

Deleting Data

Standard RESTful APIs should use the HTTP DELETE method, but Machbase methods use the HTTP GET Method to send a delete query. Below is an example of deleting data from test_table.

curl -G "" --data-urlencode 'q=delete from test_table except 1 rows'

Creating, Altering, and Dropping Table

In Machbase, any query can be performed using the HTTP GET method. Therefore, the TABLE CREATE, ALTER, and DROP commands are also available.

curl -G "" --data-urlencode 'q=drop table test_table'

  • No labels