restfulAPI 문서 작성하는 방법

API가 세상을 집어삼키고 있다는 말이 사실이라면, API를 이해하기 쉽고 사용하기도 쉽게 만드는 일이 굉장히 중요해 진다. API 문서를 일종의 요리법이라고 생각해본다면, 잘 작성된 요리법을 따라 요리사가 멋진 음식을 만들 듯이, 간결하면서 유익하며 읽기에도 쉬운 API문서가 있어야만 다른 개발자들이 API를 사용하여 멋진 무언가를 만들 수 있다.

1. 코드를 작성하기 전에 스스로에게 도움이 되기

API를 잘 설계해 두었다면 문서화하기도 쉬울 것이다. 일관성을 유지해야한다. 일관된 명명 규칙을 사용하고 기존의 표준을 따른다면, 한번만 문서화를 해도 된다. HTTP 상태 코드를 예로 들면, 의미를 왜곡시키지말고, 새로운 상태 코드를 만들지도 않아야 한다!

• 역시 200은 정상(OK)이라는 의미이고, 404는 찾지 못했다(Not Found)라는 의미이다.

HTTP 메소드도 마찬가지다. 새로 만들 땐 POST, 삭제는 DELETE를 사용해야 한다. 이들은 이미 정립된 규약이다. 단 하나의 예외가 있다면 PUT과 PATCH이다. 이 메소드들은 아직 문서가 불분명하다.

2. 사용자 관점에서 문서 작성하기

사용자들은 여러분이 작업할 때 생각하는 방식으로 API에 접근한다는 점을 기억해야 한다. 예를 들어, 여러분이 결제 처리기를 제공한다면, 사용자들은 요금과 환불, 소비자, 신용카드 등을 떠올릴 것이다. 그렇다면 API문서 역시도 이런 과정들을 그룹화 해야 한다. 깃헙은 훌륭한 RESTfulAPI 문서의 모범을 제공한다.

3. URI를 전면에 내세우거나 중심에 두지 말아야한다

문서에서 URI를 가장 명확하게 만드는 방법은 사용자에게 API 로직과 HTTP 클라이언트 사이의 연결 관계를 이해시키는 것이다. 많은 사용자들이 URI를 하드코딩하기 때문에, 만약에 여러분이 하이퍼링크가 포함된 콘트롤을 사용하다가 변경한다면 API를 사용하는 클라이언트들도 망가질 것이다.

4. 글쓰기 도구로 작성하기

가능한 한 글쓰기에 적합한 형태로 작성해야 한다.

5. 예제 코드는 자동으로 생성하고, 설명과 잘 연결되어야 한다

6. 미래를 대비해야 한다

리처드슨의 성숙도 모델을 통해 여러분의 API가 어느 단계에 와 있는 지 알 수 있다. 문서화 도구가 허용하는 범위 이상으로 코드를 RESTful하게 하고 싶다면(혹은 그럴 계획이 있다면), 문서화 도구가 발목을 잡을지도 모른다.