이번에 RESTful 한 API를 만들며 알게 된 지식 및 자료들을 정리해놓는다.

1. REST API 이해하기

조대협님의 블로그로부터 REST API를 이해하기 위한 좋은 자료를 소개한다. REST API의 이해와 설계 - 1. 개념 소개 REST API의 이해와 설계 - 2. API 설계 가이드 REST API의 이해와 설계 - 3. API 보안

위의 글을 다 읽으면 REST API가 뭔지, 어떻게 설계하는게 좋은지, 보안은 어떻게 할 지에 대한 대략적인 감을 잡을 수 있다.

2. REST API Modelling

REST API Modelling Language: RAML 라는 언어를 이용하여 REST API의 resources, methods, query parameter 등을 정의하고, 해당하는 API의 Example, Request, Response 등을 간단하게 서술하여 REST API를 모델링 할 수 있다.

Modelling 하는 데에 좋은 도구로 내가 사용해 본 것은 세 가지가 있는데, 1. Swagger 2. Atom EditorAPI Workbench 라는 Packages 3. npm에서 제공하는 api-designer

각자 장단점이 있다.

항목 장점 단점 특징
Swagger 사용하기 편함 무료로는 기능이 제한적 Web UI, 3rd vendor에서 제공
API Workbench 무료 Atom Editor 안에서만 동작 아직 베타 버전
api-designer 무료, 가벼움 저장 기능이 제한적 HTML 5의 Local Storage에 저장 (따로 저장 메커니즘 구현 해야)

API Workbench가 꽤나 괜찮은 편임에도, Atom Editor를 안에서만 동작을 하기에 크롬북을 쓰는 나에게는 약간 제한 사항이었다. 그래서 연구실의 PC에서 개발을 할 때는 API Workbench를, 크롬북으로 개발을 할 때는 api-designer를 사용하고 있다.

Swagger의 경우는 정말 좋기는 한데 무료에는 기능 제한이 은근 있어서… 그게 아쉽다.

3. JSON API Specification 따르기

아마 XML로 값을 반환하는 경우는 특별한 경우를 제외하고는 없을 것이다. 요즘에는 다 JSON이니깐…! (Thanks to Douglas Crockford!) 이를 API에 도입하기 위해서는 물론 아무렇게나 해도 상관 없지만, 확장성을 위해서라면 국제적인 표준을 따르도록 하자.

http://jsonapi.org/