REST API

실행 조건

바른의 API는 기본적으로 grpc를 기반으로 동작합니다. REST 방식에 비해서 더 빠른 속도를 제공할 뿐 아니라 안정성도 매우 높습니다.

반면에 많은 REST 방식을 선호하는 개발자 또는 환경도 있습니다. envoyproxy 라는 기술을 이용하게 되면 손쉽게 REST 방식의 API를 제공할 수 있게 됩니다. 이를 이용해서 REST 방식도 지원하게 되었습니다.

REST API 포트

도커 버전에서는 5757

도커 버전을 사용할 때에는 5757로 요청을 하면, grpc 나 REST, grpc-web을 모두 한번에 처리합니다. 아래 예시는 모두 이 포트를 사용하여 표시됩니다. 참고로 이 포트를 통해서 3가지 서비스를 동시에 처리할 수 있습니다. - grpc API - REST API - grpc-web API

일반 설치 버전에서는 5655

v3.0.rc2 버전부터는 5655 포트를 통해서 REST 방식의 API를 지원합니다. 리눅스, 맥, 윈도우용 설치 버전은 모두 이 포트를 통해서 REST 서비스를 받을 수 있습니다.

API URL 및 기능

기능	URL	HTTP/1.1 METHOD
형태소 분석	`/bareun/api/v1/analyze`	POST
형태소 분석(문장 분할 X)	`/bareun/api/v1/analyze-list`	POST
단어 분리	`/bareun/api/v1/tokenize`	POST
사용자 사전 조회	`/bareun/api/v1/customdict`	GET
사용자 사전 가져오기	`/bareun/api/v1/customdict/{domain}`	GET
사용자 사전 수정	`/bareun/api/v1/customdict/{domain}`	POST
사용자 사전 삭제	`/bareun/api/v1/customdict/delete`	POST
사용자 사전 충돌 검사	`/bareun/api/v1/customdict/check-conflict`	POST
맞춤법 검사	`/bareun/api/v1/correct-error`	POST

전체 URL

위에서 도커를 실행할 때 사용하는 포트를 추가하면 전체 URL은 다음과 같습니다.

http://localhost:5757/bareun/api/v1/analyze

curl 과 같은 도구를 통해서 API를 테스트하려면 아래와 같이 하면 됩니다.

예제

형태소 분석

curl -H "api-key: koba-ABCDEFG-1234567-LMNOPQR-7654321" \
  -X POST http://localhost:5757/bareun/api/v1/analyze \
  -d '{"document": {"content": "안녕하세요. 반가워요.","language": "ko-KR"}, "encoding_type": "UTF8", "custom_dict_names": ["testDomain"]}'

형태소 분석(문장 분할 X)

curl -H "api-key: koba-ABCDEFG-1234567-LMNOPQR-7654321" \
  -X POST http://localhost:5757/bareun/api/v1/analyze-list \
  -d '{"document": {"sentences": ['안녕하세요.', '바른 형태소분석기입니다.', '만나서 반갑습니다.'], "language": "ko-KR"}, "encoding_type": "UTF8", "custom_dict_names": ["testDomain"]}'

단어 분리

curl -H "api-key: koba-ABCDEFG-1234567-LMNOPQR-7654321" \
  -X POST http://localhost:5757/bareun/api/v1/tokenize \
  -d '{"document": {"content": "안녕하세요. 반가워요.","language": "ko-KR"}, "encoding_type": "UTF8"}'

사전 목록 가져오기

모든 등록된 커스텀 사전에 대한 이름과 메타 정보를 반환합니다. 현재 서비스 되고 있는 사전의 목록을 여기에서 확인할 수 있습니다.

curl  -H "api-key: koba-ABCDEFG-1234567-LMNOPQR-7654321" \
  http://localhost:5757/bareun/api/v1/customdict

사전 가져오기

위 사전목록 가져오기 API를 통해서 모든 사전의 목록을 확인한 다음, 개별 사용자 사전의 내용을 다운로드할 수 있습니다.

curl   -H "api-key: koba-ABCDEFG-1234567-LMNOPQR-7654321" \
  http://localhost:5757/bareun/api/v1/customdict/mydomain

사용자 사전 수정 또는 생성

앞에서 다운로드 받은 데이터 형식 그대로 내용을 바꿔서 사전을 업데이트할 수 있습니다. URL은 같지만, 이제는 POST 방식으로 보냅니다.

curl  -H "api-key: koba-ABCDEFG-1234567-LMNOPQR-7654321" \
  -X POST http://localhost:5757/bareun/api/v1/customdict/mydomain \
  -d '{ "domain_name": "mydomain", \
     "dict": \
       {"domain_name": "mydomain", \
         "np_set": { \
           "items": { \
              "광화문": 1 \
              "숭례문": 1 \
              "흥인지문": 1 \
           }, "type": "WORD_LIST", "name": "np_set"}, \
         "cp_set": { \
           "items": {\
              "논밭": 1 \
              "봄비": 1 \
              "자유여행": 1 \
           }, "type": "WORD_LIST", "name": "cp_set"},\
          "cp_caret_set": { \
           "items": { \
              "가격^파괴": 1 \
              "소비자^만족": 1 \
              "블루투스^이어폰": 1 \
           },"type": "WORD_LIST", "name": "cp_caret_set"}}}'

사용자 사전 삭제

사전을 삭제할 때는 전체를 삭제할 수도 있고, 일부만 삭제할 수도 있습니다. "all" : true 이면 모든 내용을 삭제합니다.

curl -H "api-key: koba-ABCDEFG-1234567-LMNOPQR-7654321" \
  -X POST http://localhost:5757/bareun/api/v1/customdict/delete \
  -d '{"domain_names": ["mydomain"],"all": true}'

사용자 사전 충돌 검사

하나 이상의 사전을 동시에 사용할 수 있기 때문에 의도하지 않은 결과를 가져올 수 있습니다. 사용자 사전을 두 개 이상 지정하여 비교할 수 있습니다.

curl -H "api-key: koba-ABCDEFG-1234567-LMNOPQR-7654321" \
  -X POST http://localhost:5757/bareun/api/v1/customdict/check-conflict \
  -d '{"domain_names": ["compare1", "compare2"]}'

맞춤법 검사

어법, 띄어쓰기, 표준어 등을 교정할 문장을 보내면 됩니다.

curl -H "api-key: koba-ABCDEFG-1234567-LMNOPQR-7654321" \
  -X POST http://localhost:5757/bareun/api/v1/correct-error \
  -d '{"document": {"content": "밥이 떡처럼 되서 못먹었어요","language": "ko-KR"}, "encoding_type": "UTF32", "custom_dict_names": ["testDomain"]}'

API 규격

형태소 분석

기능: 가장 핵심적인 형태소 분석을 수행합니다.
Path: /bareun/api/v1/analyze
Method: POST

요청

이름	서브	설명
document	{}	입력 문서
	content	문서 및 문장이 들어갑니다. 여러 문장이라면 줄바꿈으로 구분해도 됩니다. 만일 자동 줄바꿈을 원한다면, `auto_split_sentence` 옵션을 켜면 됩니다.
	language	현재는 한국어만 지원하므로 지정하지 않아도 됩니다. ISO 또는 BCP-47 언어코드가 사용됩니다. ko_KR 과 같이 입력하면 됩니다.
encoding_type	-	`UTF8`, `UTF16`, `UTF32` 중에서 선택합니다. 통상적으로 개발 언어별로 그 쓰임새가 다릅니다. 파이썬 3의 경우는 `UTF32`, 자바의 경우는 `UTF16`, C나 golang의 경우에는 `UTF8`을 쓰면 됩니다.
auto_split_sentence	-	여러 문장이 함께 올 경우 문장 분할 기능을 수행할지 여부, 기본적으로 줄바꿈 단위로 분장을 분할한다.
auto_spacing	-	자동으로 띄어쓰기를 수행할지 여부를 정합니다. 라이브러리에서 기본값을 `true`로 둡니다. `REST`에서는 직접 지정해야 합니다.
auto_jointing	-	자동으로 붙여쓰기를 수행할지 여부를 정합니다. 라이브러리에서 기본값을 `true`로 둡니다. `REST`에서는 직접 지정해야 합니다.
custom_domain	-	사용할 사용자 사전의 이름을 지정합니다. 이 사용자 사전의 이름은 별도의 API를 통해서 미리 등록되어 있어야 합니다. 사용하려는 사전 이름이 없으면 무시됩니다. ~~폐기되었습니다.~~
custom_dict_names	-	사용할 사용자 사전의 이름을 지정합니다. 미리 등록된 사전을 여러 개 지정할 수 있습니다. 적용 순서는 먼저 지정한 사전부터 적용됩니다.

형태소 분석(문장 분할 하지 않음)

기능: 형태소 분석을 수행하되 복수의 입력 문장의 순서를 그대로 반환하고 문장을 분할하지 않습니다.
Path: /bareun/api/v1/analyze-list
Method: POST

요청

변수	설명
sentences	배열로 이루어진 텍스트를 넣습니다.
language	현재는 한국어만 지원하므로 지정하지 않아도 됩니다. ISO 또는 BCP-47 언어코드가 사용됩니다. ko_KR 과 같이 입력하면 됩니다.
encoding_type	`UTF8`, `UTF16`, `UTF32` 중에서 선택합니다. 통상적으로 개발 언어별로 그 쓰임새가 다릅니다. 파이썬 3의 경우는 UTF32, 자바의 경우는 `UTF16`, C나 golang의 경우에는 `UTF8`을 쓰면 됩니다.
auto_spacing	자동으로 띄어쓰기를 수행할지 여부를 정합니다. 라이브러리에서 기본값을 `true`로 둡니다. REST에서는 직접 지정해야 합니다.
auto_jointing	자동으로 붙여쓰기를 수행할지 여부를 정합니다. 라이브러리에서 기본값을 `true`로 둡니다. REST에서는 직접 지정해야 합니다.
custom_domain	사용할 사용자 사전의 이름을 지정합니다. 이 사용자 사전의 이름은 별도의 API를 통해서 미리 등록되어 있어야 합니다. 사용하려는 사전 이름이 없으면 무시됩니다.
custom_dict_names	-

응답

이름	Sub1	Sub2	Sub3	Sub4	설명
sentences	[]				한 개 이상의 문장으로 구분됩니다.
	refined				문장의 띄어쓰기, 붙여쓰기 등으로 바뀌었으면 정제되었다고 표시
	text	{}			문장의 전체 텍스트 조각
		content			문장의 내용
		begin_offset			문장의 시작 위치
		length			문장의 길이
	tokens	[]			어절의 배열
		text	{}		어절의 텍스트 조각
			content		어절의 내용
			begin_offset		어절의 시작 위치
			length		어절의 길이
		lemma			원형
		tagged			태깅 형태로 만든 문자열
		modified			붙여쓰기한 경우, 붙여진 결과
		morphemes	[]		형태소의 배열
			text	{}	형태소의 텍스트 조각
				content	형태소의 내용
				begin_offset	형태소의 시작 위치
				length	형태소의 시작 위치
			tag		형태소 태그, 모두 47개의 품사가 사용됩니다.
			probability		형태 분류의 정확도
			out_of_vocab		형태 분류 중 사전 활용의 결과 표시. `IN_WORD_EMBEDDING`: 워드임베딩에 포함된 내용 `OUT_OF_VOCAB`: 자동 추측 `IN_CUSTOM_DICT`: 사용자 제공 사전에 있는 내용 `IN_BUILTIN_DICT` : 기본 사전에 포함된 내용
			custom_dict_name		사용자 사전에서 지정된 단어일 경우, 그 사전의 이름을 표시합니다.
language					이 응답의 언어, ko_KR이 기본으로 사용됩니다.

사용자 사전 조회

기능: 사용자 사전 조회
Path: /bareun/api/v1/customdict
Method: GET

요청

요청에 보낼 내용은 없습니다.

응답

이름	Sub1	Sub2	설명
domain_dicts	[]		하나 이상의 meta 데이터
	domain_name		사전의 이름
	np_set	{}	고유명사 사전 정보
		name	사전의 이름
		items_count	사전 크기 정보
		type	"WORD_LIST"
	cp_set	{}	복합명사 사전 정보
		name	사전의 이름
		items_count	사전 크기 정보
		type	"WORD_LIST"
	cp_caret_set	{}	복합명사 분리 사전 정보
		name	사전의 이름
		items_count	사전 크기 정보
		type	"WORD_LIST"
	vv_set	{}	동사사전 정보
		name	사전의 이름
		items_count	사전 크기 정보
		type	"WORD_LIST"
	va_set	{}	형용사 사전 정보
		name	사전의 이름
		items_count	사전 크기 정보
		type	"WORD_LIST"

사용자 사전 가져오기

기능: 사용자 사전 조회
Path: /bareun/api/v1/customdict/{domain}
Method: GET

요청

URL의 {domain} 위치에 요청할 도메인 정보를 넣어서 보냅니다.
예를 들면, http://localhost:5757/bareun/api/v1/customdict/mydomain

응답

이름	Sub1	Sub2	Sub3	설명
domain				응답 도메인 이름
dict	domain_name
	np_set	{}		고유명사 사전 정보
		name		사전의 이름
		type	"WORD_LIST"
		items	[]	실제 사전 내용 정의 시작
			KEY	사전 텍스트
			VALUE	0이 아닌 정수값
	cp_set	{}		복합명사 사전 정보
		name		사전의 이름
		type	"WORD_LIST"
		items	[]	실제 사전 내용 정의 시작
			KEY	사전 텍스트
			VALUE	0이 아닌 정수값
	cp_caret_set	{}		복합명사 분리 사전 정보
		name		사전의 이름
		type	"WORD_LIST"
		items	[]	실제 사전 내용 정의 시작
			KEY	사전 텍스트
			VALUE	0이 아닌 정수값
	vv_set	{}		동사사전 정보
		name		사전의 이름
		type	"WORD_LIST"
		items	[]	실제 사전 내용 정의 시작
			KEY	사전 텍스트
			VALUE	0이 아닌 정수값
	va_set	{}		형용사사전 정보
		name		사전의 이름
		type	"WORD_LIST"
		items	[]	실제 사전 내용 정의 시작
			KEY	사전 텍스트
			VALUE	0이 아닌 정수값

사용자 사전 수정

기능: 사용자 사전 수정
URL: /bareun/api/v1/customdict/{domain}
Method: POST

요청

이름	Sub1	Sub2	Sub3	설명
domain				응답 도메인 이름
dict	domain_name
	np_set	{}		고유명사 사전 정보
		name		사전의 이름
		type	"WORD_LIST"
		items	[]	실제 사전 내용 정의 시작
			KEY	사전 텍스트
			VALUE	0이 아닌 정수값
	cp_set	{}		복합명사 사전 정보
		name		사전의 이름
		type	"WORD_LIST"
		items	[]	실제 사전 내용 정의 시작
			KEY	사전 텍스트
			VALUE	0이 아닌 정수값
	cp_caret_set	{}		복합명사 분리 사전 정보
		name		사전의 이름
		type	"WORD_LIST"
		items	[]	실제 사전 내용 정의 시작
			KEY	사전 텍스트
			VALUE	0이 아닌 정수값
	vv_set	{}		동사사전 정보
		name		사전의 이름
		type	"WORD_LIST"
		items	[]	실제 사전 내용 정의 시작
			KEY	사전 텍스트
			VALUE	0이 아닌 정수값
	va_set	{}		형용사사전 정보
		name		사전의 이름
		type	"WORD_LIST"
		items	[]	실제 사전 내용 정의 시작
			KEY	사전 텍스트
			VALUE	0이 아닌 정수값

응답

이름	서브	설명
updated_domain_name	-	수정된 도메인 이름.

사용자 사전 삭제

기능: 사용자 사전 삭제
URL: /bareun/api/v1/customdict/delete
Method: POST

요청

이름	서브	설명
domain_names	[]	삭제할 도메인의 배열.
	VALUE	삭제할 도메인
all		모두 삭제 여부, `true` 이면 모든 사용자 사전 삭제

응답

이름	서브	설명
deleted_domain_names	{}	객체 형식으로 반환
	KEY	-
	VALUE`\| - \|`true`또는`false`

맞춤법 검사

기능: 어법, 띄어쓰기, 표준어 등을 검사하고 교정합니다.
Path: /bareun/api/v1/correct-error
Method: POST

요청

이름	서브	설명
document	{}	입력 문서
	content	문서 및 문장이 들어갑니다. 여러 문장이라면 줄바꿈으로 구분해도 됩니다. 만일 자동 줄바꿈을 원한다면, `auto_split_sentence` 옵션을 켜면 됩니다.
	language	현재는 한국어만 지원하므로 지정하지 않아도 됩니다. ISO 또는 BCP-47 언어코드가 사용됩니다. ko_KR 과 같이 입력하면 됩니다.
encoding_type	-	`UTF8`, `UTF16`, `UTF32` 중에서 선택합니다. 통상적으로 개발 언어별로 그 쓰임새가 다릅니다. 파이썬 3의 경우는 `UTF32`, 자바의 경우는 `UTF16`, C나 golang의 경우에는 `UTF8`을 쓰면 됩니다.
custom_dict_names	-	사용할 사용자 사전의 이름을 지정합니다. 이 사용자 사전의 이름은 별도의 API를 통해서 미리 등록되어 있어야 합니다. 사용하려는 사전 이름이 없으면 무시됩니다.
config	{}	상세한 호출 옵션입니다.
	disable_split_sentence	문장 단위를 분할하지 않습니다. 기본값이므로 사용하지 않는 것이 좋습니다.
	disable_caret_spacing	복합명사의 분리 사전을 적용하지 않습니다. 기본적으로 적용합니다. "인공지능"이라는 붙여 쓴 단어를 만나면, 원 정의가 "인공^자눙"이므로 "인공 지능"으로 분리해 냅니다.
	disable_vx_spacing	보조 용언의 띄어쓰기를 최소화 합니다. 기본적으로 보조 용언을 최대한 띄어 씁니다. 이게 기본적인 띄어쓰기 검사의 규칙입니다.
	treat_as_title	문장을 제목으로 다룹니다. 제목으로 사용하는 문장에서는 구두점을 비롯한 일부 처리가 달라집니다.
	enable_cleanup_whitespace	문장에 포함된 불필요한 공백을 제거합니다. 특히, 문장의 시작이나 끝에 붙어 있는 불필요한 공백을 제거하도록 할 수 있습니다.
	enable_sentence_check	문장 내 호응 관계까지 분석합니다.

응답

변수	서브	설명
origin		원래 요청 문서의 전체 문장
revised		교정 문서 전체
revised_blocks[]		교정의 블럭을 제시하여 다양한 교정 행위를 수행할 수 있다.
	origin	교정대상의 위치를 포함하는 원문의 텍스트
	revised	교정된 결과물, 여러가지 중에 하나로서 가장 대표적인 경우
	revisions	다양한 교정 예시들, 교정의 카테고리, 도움말 ID 정보를 포함
	nested	여러 개의 블럭을 하나로 합친 경우에는 원래의 블럭이 틀리지 않았을 것이므로 이들을 포함하여 내부에 가지도록 한다. 다만 이 nested 블럭은 각각은 개별 수정만을 포함하고 있으므로 제대로 모든 블럭을 다 가지고 있을 수 없다. 고급 사용의 경우, 해당 내용만을 수정에 반영할 수 있도록 하기 위해서 마련되었다.
	lemma	사용사 사전에 추가하기 위한 기본 단위, nested가 존재하는 쓸 수 없다.
	pos	사용사 사전에 추가할 품사
whitespace_cleanup_ranges[]		교정 대상에서 지워야할 공백들의 목록
	offset	위치
	length	길이
	position	`START`, `END`, `MIDDLE` 등 3가지 값을 가집니다.
revised_sentences[]		전체 문장 단위 교정, 문장은 자동으로 분리되어서 나타난다.
	origin	교정 대상의 문장
	revised	교정된 문장
helps{}
	id	도움말 ID, 고정된 도움말이 있을 수 있고, 동적으로 생성되는 도움말이 있을 수 있다.
	category	교정의 카테고리
	comment	바뀌어야 하는 이유에 대한 설명
	examples[]	변경이 될 수 있는 문장들
	rule_article	관련 규정
language		텍스트의 언어, 만일 언어가 지정되지 않은 경우에는 자동으로 탐지하여 반환한다. 언어가 지정된 경우에는 동일한 언어를 반환한다. 이때, 언어는 ko_KR 등과 같이 사용한다.

도움이 되었나요?