RESTful API

RESTful API 개요

Representational State Transfer (REST) 는 소프트웨어 구조 스타일 의 일종으로, 확장 가능한 웹 서비스에서 제공하는 인터페이스의 가이드라인과 모범적인 규범들로 구성되어 있다.

HTTP protocol에 정의된 4개의 Method 들이 Resource에 대한 CRUD를 정의한다.

HTTP Method	의미
POST	Create
GET	Select
PUT	Update
DELETE	Delete

마크베이스는 표준 RESTful API 방식이 아니라, POST와 GET method만을 이용하여 CRUD를 처리하는 방식으로 RESTful API라고 할 수 있다.

즉, 데이터 입력에는 POST method를 사용하고 나머지는 SQL query를 GET Method parameter로 전달하여 모든 작업을 할 수 있도록 구성되어 있다.

사용 환경 설정

$MACHBASE_HOME/webadmin/flask/MWAserver start를 이용해서 Machbase Web Analytics(MWA)를 실행시키면 마크베이스 서버를 Restful API를 이용해서 접근할 수있다.

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

사용 방법

마크베이스 RESTful API는 MWA의 서버 설정과 연동하여 사용할 수 있다. RESTful API를 사용할 때 's' 파라미터로 사용할 서버의 ID 또는 Server name을 지정하여 주면 된다.

ex) 아래의 예는 MWA에 설정된 서버 중 ID가 3(또는 server name 이 sample_server)인 서버에 해당 쿼리를 보내서 결과를 받는다

curl -G "http://127.0.0.1:5001/machbase" --data-urlencode 'q=select * from m$sys_tables' --data 's=3'
# 또는
curl -G "http://127.0.0.1:5001/machbase" --data-urlencode 'q=select * from m$sys_tables' --data 's=sample_server'

지정한 서버의 ID 또는 name을 발견할 수 없다면 404 에러와 함께 아래의 json을 결과로 돌려준다.

curl -G "http://127.0.0.1:5001/machbase" --data-urlencode 'q=select * from m$sys_tables' --data 's=not_exist'
{
  "error": "Cannot found server."
}

기본 URL

Restful API의 기본 url은 다음과 같다.

http://hostname:port 는 MWA를 접속하기위한 url로 MWA를 구동하기 위해 MWAserver start 명령을 실행하면 알 수 있다.

Data 추출

HTTP GET method를 이용하여 data를 가져온다. 리턴값은 json type이다. 실행하고자 하는 query문을 'q' 파라미터를 사용해서 넘겨주면 된다. 아래 query는 table 목록을 가져온다.

curl -G "http://127.0.0.1:5001/machbase" --data-urlencode 'q=select * from m$sys_tables'

Data 입력

HTTP POST method를 이용하여 json type의 입력값을 파라미터로 보내면 된다. 아래는 3개의 컬럼을 가진 test_table에 데이터를 입력하는 예제이다.

먼저 curl GET method를 이용해서 테이블을 생성하는 쿼리를 실행한다.

curl -X GET "http://127.0.0.1:5001/machbase" --data-urlencode 'q=create table test_table(c1 short, c2 integer, c3 varchar(20))'

curl 명령어를 이용하여 POST method로 data를 입력한다. data 입력 json은 4개의 key를 사용할 수 있으며, 'name'과 'values' key는 반드시 입력해야 한다.

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

key	설명	비고
name	입력 테이블 명	필수
values	입력할 data를 2차원 array로 입력	필수
date_format	사용할 date format	date type을 사용하는 경우
s	서버 ID 또는 name	MWA에 정의된 server

date type을 입력하는 경우에는 date format을 지정해주어야 한다. date format은 마크베이스에서 사용하는 pattern을 사용해야 한다. 따로 지정하지 않았을 경우에는 YYYY-MM-DD HH24:MI:SS mmm:uuu:nnn 인피니플럭스 기본 포맷으로 설정되며 date format이 맞지 않을 경우에는 결과값이 제대로 반환되지 않는다. date and time pattern을 지정할때 대소문자에 주의하여야 한다.

curl -X GET "http://127.0.0.1:5001/machbase" --data-urlencode 'q=create table test_date(c1 datetime)'

curl -X POST -H "Content-Type: application/json" "http://127.0.0.1:5001/machbase" -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"]]}'

Data 삭제

표준 RESTful API는 HTTP DELETE method를 이용하여야 하지만, 마크베이스에서는 HTTP GET Method를 이용하여 삭제 query를 보내는 방법을 사용한다. 아래는 test_table에서 data를 삭제하는 경우의 예제이다.

curl -G "http://127.0.0.1:5001/machbase" --data-urlencode 'q=delete from test_table except 1 rows'

Table 생성, 변경 및 삭제

마크베이스에서는 HTTP GET Method를 이용하여 어떤 query라도 수행할 수 있다. 따라서 TABLE CREATE, ALTER, DROP 명령어도 가능하다.

curl -G "http://127.0.0.1:5001/machbase" --data-urlencode 'q=drop table test_table'

Machbase 5 Manual