/
RESTful API

RESTful API

Owned by Kyle Song (Unlicensed)
Last updated: Nov 08, 2021 by Grey Shim

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 6.5 RestAPI

Machbase에 웹서버를 내장하여 별도의 서버 구동 없이 Machbase에 직접 RestAPI를 수행하는 기능이다.


RestAPI 지원 Machbase Edition

Edge / Fog / Cluster (개발 중)


RestAPI 지원 Table 종류

Tag Table / Log Table / Lookup Table / Volatile Table


Configuration 설정

machbase.conf 와 http.conf 두 가지 설정 파일이 존재한다.

  • machbase.conf : Rest API를 사용하기 위해 HTTP 서버를 사용할 지와 최대 메모리 사용량 등 HTTP Server에 대한 설정을 저장
  • http.conf : HTTP Web Server 자체에 대한 설정을 저장

설정 파일을 수정 하면 machbase 서버를 다시 시작해야 변경 내용이 적용된다.


버전별 .conf 파일의 위치

Edge / Fog 버전

$MACHBASE_HOME/conf/machbase.conf

$MACHBASE_HOME/http/conf/http.conf

Cluster 버전

EACH_BROKER_HOME/conf/machbase.conf (Broker 별로 모두 수정)

EACH_BROKER_HOME/http/conf/http.conf (Broker 별로 모두 수정)


각 .conf 파일 Property 설명

machbase.conf (PROPERTY = VALUE 형태로 설정)

Property

설명

HTTP_ENABLE

내장 웹 서버를 구동할 지 여부

0 : 구동 안함, 1 : 구동

HTTP_PORT_NO

내장 웹 서버 접속 Port 번호

Port 범위 : 0 ~ 65535

Default : 5657

HTTP_MAX_MEM

하나의 Web Session에서 사용할 최대 메모리

Min : 1048576 (1MB)

Default : 536870912 (512MB)

HTTP_AUTH

내장 웹 서버 사용 시 기본 인증을 사용할 지 여부

0 : 인증 사용 안함, 1 : 인증 사용함

http.conf (JSON 형식으로 설정)

Property

설명

document_root

$MACHBASE_HOME 기준의 html 파일 위치

Default : http/html ($MACHBASE_HOME/http/html)

max_request_size1회 요청의 최대 요청 byte 크기 제한

request_timeout_ms

1회 요청의 최대 응답 대기 시간 (millisecond)
enable_auth_domain_check

도메인 인증을 활성화 할지 여부

"yes" or "no" 값으로 설정

Default : "no"

reverse_proxy

요청 URL을 특정 URL로 변경

참고: https://brainbackdoor.tistory.com/113


각 .conf 파일 Sample

machbase.conf
#################################################################################
# Rest-API port
#################################################################################
HTTP_PORT_NO = 5657
 
#################################################################################
# Maximum memory per web session.
# Default Value: 536870912 (512MB)
#################################################################################
HTTP_MAX_MEM = 536870912
 
#################################################################################
# Min Value:     0
# Max Value:     1
# Default Value: 0
#
# Enable REST-API service.
#################################################################################
HTTP_ENABLE = 0
 
#################################################################################
# Min Value:     0
# Max Value:     1
# Default Value: 0
#
# Enable Basic Authentication for Rest-API service
#################################################################################
HTTP_AUTH = 0
http.conf
{
    "document_root":"http/html/",
    "max_request_size": "100000",
    "request_timeout_ms": "10000",
    "enable_auth_domain_check": "no",
    "reverse_proxy" : [["/machbase/tables", "http://127.0.0.1:55657/machbase"],
        ["/self_machbase_proxy", "http://127.0.0.1:55657/machbase"],
        ["/dead_proxy", "http://127.0.0.0/machbase"]]
}


RestAPI 사용

DDL / DML / Append 수행 가능

기본 요청 형식 

http://addr:port/machbase?q=query&f=dateformat

응답 형식 DDL / Append / DML (except Select)

{"error_code":0, "error_message" :"Message", "data":[]}

응답 형식 DML (Select)

{"error_code":0, "error_message" :"Message", "columns":[Columns], "data":[Data]}

DDL Sample

## 테이블 생성 요청
curl -G "http://127.0.0.1:5657/machbase" --data-urlencode 'q=create table test_table (name varchar(20), time datetime, value double)'
 
## 정상 응답
{"error_code":0, "error_message" :"No Error", "data":[]}
 
## 테이블 삭제 요청
curl -G "http://127.0.0.1:5657/machbase" --data-urlencode 'q=drop table test_table'
 
## 정상 응답
{"error_code":0, "error_message" :"No Error", "data":[]}

DML Sample

## 로그 테이블 입력(Insert) 요청
curl -G "http://127.0.0.1:5657/machbase" --data-urlencode 'q=insert into test_table values ("test", "1999-01-01 00:00:00", 0)'
 
## 정상 응답
{"error_code":0, "error_message" :"No Error", "data":[]}
 
## 로그 테이블 조회 요청
curl -G "http://127.0.0.1:5657/machbase" --data-urlencode 'q=select * from test_table'
 
## 정상 응답
{"error_code":0, "error_message": "", "columns" : [{"name":"NAME", "type":5, "length":20},{"name":"TIME", "type":6, "length":8},{"name":"VALUE", "type":20, "length":8}],"data" :[{"NAME":"test", "TIME":"1999-01-01 00:00:00 000:000:000", "VALUE":0.000}]}


Append Sample

## 로그 테이블 입력(Append) 요청
curl -X POST -H "Content-Type: application/json" "http://127.0.0.1:5657/machbase" -d '{"name":"test_table", "date_format":"YYYY-MM-DD","values":[["test", "1999-01-01 00:00:01", 1], ["test", "1999-01-01 00:00:02", 2], ["test", "1999-01-01 00:00:03", 3]]}'
 
## 정상 응답
{"error_code":0, "error_message" :"No Error", "data":[], "append_success":3, "append_failure":0}


Binary Append

Binary Append의 경우 Binary 데이터를 Base64로 인코딩 후 전송하면 서버에서 디코딩 후 저장하게 된다.

출력 시에는 바이너리 데이터가 Base64로 인코딩되어 반환된다.

입력 : Binary Data >> Base64 Encoding >> HTTP(POST) >> Base64 Decoding >> Append(BLOB Binary)

출력 : BLOB Binary >> Base64 Encoding >> HTTP (GET) >> Base64 Decoding >> Save or View Binary


Binary Append Sample

## 00 ~ FF까지의 256바이트 바이너리 데이터를 Base64로 인코딩 후 입력 / 출력 예
 
## 로그 테이블 입력(Append) 요청
curl  -X POST -H "Content-Type: application/json" "http://127.0.0.1:5657/machbase" -d '{"name":"test_table", "date_format":"YYYY-MM-DD","values":[["AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8gISIjJCUmJygpKissLS4vMDEyMzQ1Njc4OTo7PD0+P0BBQkNERUZHSElKS0xNTk9QUVJTVFVWV1hZWltcXV5fYGFiY2RlZmdoaWprbG1ub3BxcnN0dXZ3eHl6e3x9fn+AgYKDhIWGh4iJiouMjY6PkJGSk5SVlpeYmZqbnJ2en6ChoqOkpaanqKmqq6ytrq+wsbKztLW2t7i5uru8vb6/wMHCw8TFxsfIycrLzM3Oz9DR0tPU1dbX2Nna29zd3t/g4eLj5OXm5+jp6uvs7e7v8PHy8/T19vf4+fr7/P3+/w=="]]}'
 
## 정상 응답
{"error_code":0, "error_message" :"No Error", "data":[], "append_success":1, "append_failure":0}
 
## 로그 테이블 출력 요청
curl -G "http://127.0.0.1:5657/machbase" --data-urlencode 'q=select * from test_table';
 
## Base64 데이터 출력
{"error_code" :0, "error_message": "No Error", "columns" : [{"name":"V1", "type":57, "length":67108864}],"data" :[{"V1":"AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8gISIjJCUmJygpKissLS4vMDEyMzQ1Njc4OTo7PD0+P0BBQkNERUZHSElKS0xNTk9QUVJTVFVWV1hZWltcXV5fYGFiY2RlZmdoaWprbG1ub3BxcnN0dXZ3eHl6e3x9fn+AgYKDhIWGh4iJiouMjY6PkJGSk5SVlpeYmZqbnJ2en6ChoqOkpaanqKmqq6ytrq+wsbKztLW2t7i5uru8vb6/wMHCw8TFxsfIycrLzM3Oz9DR0tPU1dbX2Nna29zd3t/g4eLj5OXm5+jp6uvs7e7v8PHy8/T19vf4+fr7/P3+/w=="}]}
 
## machsql을 통한 HEX Dump 값 확인
select to_hex(v1) from test_table;
to_hex(v1)                                                                      
------------------------------------------------------------------------------------
000102030405060708090A0B0C0D0E0F101112131415161718191A1B1C1D1E1F2021222324252627
28292A2B2C2D2E2F303132333435363738393A3B3C3D3E3F404142434445464748494A4B4C4D4E4F
505152535455565758595A5B5C5D5E5F606162636465666768696A6B6C6D6E6F7071727374757677
78797A7B7C7D7E7F808182838485868788898A8B8C8D8E8F909192939495969798999A9B9C9D9E9F
A0A1A2A3A4A5A6A7A8A9AAABACADAEAFB0B1B2B3B4B5B6B7B8B9BABBBCBDBEBFC0C1C2C3C4C5C6C7
C8C9CACBCCCDCECFD0D1D2D3D4D5D6D7D8D9DADBDCDDDEDFE0E1E2E3E4E5E6E7E8E9EAEBECEDEEEF
F0F1F2F3F4F5F6F7F8F9FAFBFCFDFEFF                                                
[1] row(s) selected.


HTTP_AUTH Property 사용

Request Header에 'Authorization: Basic Base64String' 문자열을 포함하여 정상 유저임을 인증하도록 설정하는 옵션이다.

Base64 문자열은 ID@Host:Password 구조로 작성한다. (단, Host명은 정확하지 않아도 된다. ID, Password는 Machbase의 유저 정보를 입력해야 한다.)

인증을 위한 Basic Base64String 생성 방법
## ID: sys, Password: manager 일 경우의 생성 예
echo -n "sys@localhost:manager" | base64
 
## 생성된 Base64String
c3lzQGxvY2FsaG9zdDptYW5hZ2Vy


Base64String 사용 Sample (HTTP_AUTH = 1 인 경우)
## Authorization을 넣지 않은 요청의 예
curl -G "http://127.0.0.1:5657/machbase" --data-urlencode 'q=select * from v$stmt'
 
## 에러 발생
{"error_code":3118, "error_message" :"There is No Authorization Header.", "data":[]}
 
## Request Header에 'Authorization:Base64String' 추가한 요청의 예
curl -H "Authorization: Basic c3lzQGxvY2FsaG9zdDptYW5hZ2Vy"  -G "http://127.0.0.1:5657/machbase" --data-urlencode 'q=select * from v$stmt'
 
## 정상 응답
{"error_code":0, "error_message": "No Error", "columns" : [{"name":"ID", "type":8, "length":4},{"name":"SESS_ID", "type":8, "length":4},{"name":"STATE", "type":5, "length":64},{"name":"RECORD_SIZE", "type":8, "length":4},{"name":"QUERY", "type":5, "length":32767}],"data" :[{"ID":0, "SESS_ID":52, "STATE":"Fetch prepared", "RECORD_SIZE":0, "QUERY":"select * from v$stmt"}]}


출력 소수점 Scale 지정 (s 옵션)

응답 데이터의 소수점을 몇자리까지 출력할 지 지정

0 ~ 9 값으로 설정 (범위 값이 아닐 경우 3으로 동작)

소수점 5자리까지 출력 Sample (s=5)
## 소수점 5자리까지 출력
curl -G "http://127.0.0.1:5657/machbase" --data-urlencode 'q=select * from test_table' --data-urlencode 's=5';
 
## 정상 응답
{"error_code" :0, "error_message": "", "columns" : [{"name":"C1", "type":16, "length":4},{"name":"C2", "type":20, "length":8}],"data" :[{"C1":12345.00000, "C2":1234.01235}]}


데이터 Fetch 모드 변경 (m 옵션)

응답 data에 column 이름을 항상 붙여서 표시할 지 결정 (0 : 표시, 1 : 표시 안함)

Default Fetch mode Sample (m=0)
## fetch mode (m=0) 요청
curl -G "http://127.0.0.1:5657/machbase" --data-urlencode 'q=select * from tag limit 2' --data-urlencode 'm=0';
 
## 정상 응답 (Column Name을 포함한 결과 출력)
{"error_code" :0, "error_message": "", "columns" : [{"name":"NAME", "type":5, "length":20},{"name":"TIME", "type":6, "length":8},{"name":"VALUE", "type":20, "length":8}],
"data" :[{"NAME":"tag1", "TIME":"2001-09-09 10:46:40 000:000:000", "VALUE":1000000000.000}, {"NAME":"tag1", "TIME":"2001-09-09 10:46:41 000:000:000", "VALUE":1000000001.000}]}


Advanced Fetch mode Sample (m=1)
## fetch mode (m=1) 요청
curl -G "http://127.0.0.1:5657/machbase" --data-urlencode 'q=select * from tag limit 2' --data-urlencode 'm=1';
 
## 정상 응답 (Column Name이 생략된 결과 출력)
{"error_code" :0, "error_message": "", "columns" : [{"name":"NAME", "type":5, "length":20},{"name":"TIME", "type":6, "length":8},{"name":"VALUE", "type":20, "length":8}],
"data" :[["tag1", "2001-09-09 10:46:40 000:000:000", 1000000000.000], ["tag1", "2001-09-09 10:46:41 000:000:000", 1000000001.000]]}


NULL 값의 처리

DML의 처리 중 Insert나 Append 시 NULL 값은 그대로 null로 입력하면 된다.

Append 시 NULL 값을 포함한 JSON Sample
[["data1", "data2", "data3"],["data11", "data12", "data13"],["data21", "data22", "data23"],[null,null,null]]


Select 시의 NULL 값 포함 결과 Sample
[{"C1":null, "C2":null, "C3":null, "C4":null, "C5":null, "C6":null, "C7":null, "C8":null, "C9":null, "C10":null, "C11":null, "C12":null}]

Related content