REST API 설계 표준 따르기
이번에 RESTful 한 API를 만들며 알게 된 지식 및 자료들을 정리해놓는다.
1. REST API 이해하기 ¶
조대협님의 블로그로부터 REST 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 하는 데에 좋은 도구로 내가 사용해 본 것은 세 가지가 있는데,
- Swagger
- Atom Editor 의 API Workbench 라는 Packages
- 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에 도입하기 위해서는 물론 아무렇게나 해도 상관 없지만, 확장성을 위해서라면 국제적인 표준을 따르도록 하자.