오픈API와 오픈 플랫폼의 구성요소 [2부] - 오픈API 디자인과 문서화

[1부] 오픈 API 란 무엇인가
[2부] 오픈 API 디자인과 문서화
[3부] 오픈 플랫폼의 구성요소

1부에서 웹 API가 무엇인가에 대하여 알아보았다. 2부에서는 이러한 웹 API를 디자인하고 문서화하는 원칙과 방법에 대하여 알아보고자 한다.

웹 API 디자인 원칙

1. 개발보다 협업 설계를 우선하라(Design-first Approach)

당연한 이야기 일 수 있지만 API 개발보다 설계부터 진행해야 한다. 일반적인 어플리케이션 개발 시에는 사용자로부터의 요구사항을 분석하는 것에 익숙하지만, API는 개발자가 어플리케이션을 통하여 사용하는 시스템 자원이라는 선입견 때문에 서버 시스템이 제공할 수 있는 기능 위주로 API를 먼저 개발하고 API 스펙을 만들어 내는 경향이 있다.

또한 Spring 프레임워크의 Annotation 을 통하여 swagger 형식의 API 문서를 자동 생성해낼 수 있기도 하다. 하지만 해당 API를 누가 사용하는지 알 수 있는가? 내부 시스템 간 API 라도 다양한 어플리케이션에서 사용될 수 있기 때문에 API 동작을 확정하는게 쉽지 않다. 무엇보다도 API 는 협업의 도구이므로, 우선적으로 API 를 문서화 후 고객, 상품, 마케팅 등 다양한 조직과 API 협업 설계를 하는게 중요하다. 즉, 개발자가 아닌 현업, 유관기관, 시장조사 등 다양한 이해관계자들을 참여시켜야 API 활용성을 높일 수 있다.

2. API 들 간에 서비스 선후행 처리 흐름이 있다면 API Sequence Diagram을 작성하여 제시하는 것이 필요하다

개별 API 사양에 기록된 전제조건, 처리 결과 상태 등의 항목 만으로는 API 간 처리 흐름이 파악하기 쉽지 않다. 플랫폼에서 이해관계자간 서비스를 융복합하여 제공하는 제휴 API의 경우에는 서비스 흐름 및 처리 조건 등이 복잡해 질 수 있으므로 흐름을 쉽게 파악할 수 있는 Sequence Diagram이 유용하다. 물론 계좌 잔액조회와 같이 자체로 처리가 완결되는 API 는 예외가 될 것 이다.

투이톡_오픈api_1.jpg
[그림 1] API Sequence diagram 예시

3. API 의 응답 헤더에 HTTP 상태코드 200과 함께 에러메시지를 같이 보내지 말자

API 의 비즈니스 처리가 정상적으로 되지 않았다 해도 HTTP 호출은 정상적으로 이루어졌기 때문에 HTTP 상태코드를 200으로 설정하고 API 응답의 에러메시지 항목에 에러메시지를 설정하는 경우가 있다. 실제로 이런 사례를 경험하였다. 하지만 이럴 경우 API 사용자 입장에서는 정상처리 된 건지 아닌지 혼란스러울 수 있다. 이런 경우 HTTP 상태코드는 400 혹은 500으로 설정하고 별도의 에러메시지를 설정하는 것을 권고한다.

투이톡_오픈api_2.jpg
[그림 2] Naver 오픈 API 오류코드 일부 발췌

API 문서화(Specification)

API 설계 시 여전히 Excel 을 활용하는 곳도 있으나, Git으로 관리할 수 없어 API 버전관리뿐만 아니라, 코드로부터 자동화 할 수 없고 즉시 실행해 볼 수도 없어 협업에 어려움이 있다.

이러한 것들을 가능하게 해주는 REST API 모델링 언어 및 도구는 다음과 같다.

1. RAML(RESTful API Modeling Language)

RESTful API 를 설계하고 개발할 수 있는 YAML(YAML Ain't Markup Language) 기반의 모델링 언어이다. Apache 라이선스 2.0 에 따른다. RAML을 지원하는 업체는 다음과 같다(Mulesoft, AngularJS, Intuit, Box, PayPal, Programmable Web and API Web Science, Kin Lane, SOA Software, Cisco).

2016년 5월 16일 발표된 RAML 1.0은 현재, YAML 1.2, JSON 포맷을 사용할 수 있으며, API-Designer, API Workbench 등의 Tool로써 작성할 수 있다.

RAML 1.0 specification : https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md/

다음은 node.js 만 설치되어 있으면 npm install 명령어로 설치하여 웹 기반으로 간단히 실행할 수 있는 API Designer로 작성된 RAML API 예시이다.

투이톡_오픈api_3.jpg
[그림 3] API designer 에서의 RAML 1.0 API 예시

2. OAS 3.0 (OpenAPI Specification 3.0)

2015년에 Swagger Specification 에서 OpenAPI Initiative로 기부(OAS 2.0) 되었으며, 2017년 7월 3.0 버전이 메이저 업그레이드 되었고 현 시점에서는 2018년 10월 8일 발표된 3.0.2 버전이 최신이다. http://spec.openapis.org/oas/v3.0.2

Google, Microsoft, IBM, Paypal 의 지원을 받고 있고, RAML의 강력한 후원자 였던 MuleSoft 가 리눅스 재단의 OAI 에도 2017년 4월 참여하였다.

YAML과 JSON 포맷을 사용할 수 있으며, Swagger Editor를(https://swagger.io./tools/swaggerhub/) 통해서 REST API를 설계, 빌드, 자동문서화 및 실행해볼 수 있다.

투이톡_오픈api_4.jpg
[그림 4] Swagger Hub 에서의 OAS 3.0 API 예시

3. API Blueprint

MIT 라이선스의 오픈소스인 API Blueprint는 현재 버전은 Format 1A revision 9 이며, JSON, YAML 뿐만 아니라, Markdown 문법도 지원하고 있다.

API Blueprint Specification :
https://github.com/apiaryio/api-blueprint/blob/master/API Blueprint Specification.md

참고
1. Markdown : 일반 텍스트 문서 양식이나 쉽게 HTML 또는 XHTML 로 변환이 가능하다.
https://simhyejin.github.io/2016/06/30/Markdown-syntax/

2. YAML : HTML이 문서 표현에 집중한다면, YAML은 데이터 자체를 중요시 한다는 의미이다.

투이톡_오픈api_5.jpg

2부 정리

웹 API는 협업의 도구이므로 이해관계자들과의 협업 설계를 우선하고, 비연결이라는 웹 기술의 특징을 고려하여 웹 API를 설계하여야 한다. RAML, OAS 등 REST API를 표준 문서화하는 기술을 협업 설계에 활용하라. 이 API 문서는 3부에 이어질 APIM의 API 포탈과 API Gateway에 배포되고 관리된다.

- 끝 -

이상익 이사 다른 콘텐츠 보기