API 문서화 공부하기 3 - REST API 문서 섹션과 리소스 설명
API문서 작성을 하는 테크니컬 라이터는 문서 프로젝트를 처음부터 시작하지는 않는다. 내부 위키 페이지에 있는 정보들을 활용해서 가공해야 한다. 대부분 이 문서들은 팀 내부에 있는 엔지니어들만 알아볼 수 있는 내용들과 정리되지 않은 내용들로 이루어져 있다. 테크니컬 라이터는 이 정보를 사용자가 알아볼 수 있는 정보로 바꾸는 역할을 수행한다.
API 문서를 작성해보는 실습을 하기 위해서 공부를 하고 있는 사이트에서 가상의 위키 페이지를 제공해주었다. Surfreport API에 대한 위키 페이지이다.
(이런 식으로 가공되지 않은 정보들이 올라온다는 말인 걸까? 실제로 IT회사에서 근무해보지는 않아서 모르겠다.🙄)
보다시피 예제로 제공된 위키 페이지는 정보가 구조화되어있지 않고 사용자가 원하는 정보를 한눈에 파악하기 어렵다.
현업 제조업에서 장비 사용자 매뉴얼을 작성해왔는데, 작성하다 보면 사용자 매뉴얼에도 비슷한 구조가 반복된다는 것을 알 수 있다. API 문서도 5가지의 공통 섹션이 포함된다고 한다. 이를 토대로 위키 페이지의 정보를 가공해 실제로 기업에서 제공하는 API 문서와 같은 형태로 바꿔보는 실습이다.
REST API 문서의 5가지 공통 섹션
- 리소스(Resource) 설명
리소스는 API에서 반환한 정보를 나타낸다. 여기서 리소스는 클라이언트가 바로 접근할 수 있는 고유 URL이 존재한다. - 엔드포인트(Endpoint) 및 메서드(Method)
엔드포인트는 리소스에 접근하는 방법을 나타낸다. 엔드포인트는 같은 URL에 대해서 다른 요청을 할 수 있도록 구별하게 해주는 항목이다. 메서드는 리소스와의 허용된 상호작용(GET, POST, DELETE, PUT)을 나타낸다. - 매개변수(Parameter)
매개변수는 응답에 영향을 주기 위해 엔드포인트와 함께 전달할 수 있는 옵션이다. - 요청 예시(Request Example)
요청 예시는 엔드포인트를 사용하는 샘플 요청이 포함되어 있으며 구성된 일부 매개변수를 보여준다. - 응답 예시(Response example)와 스키마(Schema)
응답 예시는 요청 예시의 샘플 응답을 보여준다. 응답 스키마는 응답에서 가능한 모든 요소를 정의한다.
실제로 위 설명처럼 구성되어 있는지 카카오 디벨로퍼 API문서를 통해 확인해보자. 아래 이미지에서 볼 수 있듯이 인가 코드를 받는 REST API문서에 엔드포인트 그리고 메서드, 매개변수, 요청 예시, 응답 예시를 확인해볼 수 있다.
리소스 설명
리소스는 일반적으로 말하는 파일, 이미지뿐만 아니라 우리가 일반적으로 교환하는 모든 정보를 포함한다. 리소스 설명은 1-3 문장으로 간단하며 일반적으로 동사로 시작한다고 말한다. 리소스에는 리소스에 접근하려는 다양한 엔드포인트와 각 엔드포인트의 여러 메서드가 있다.
리소스 설명의 예시를 살펴보자. 일반적으로 API에는 동일한 리소스 아래에 그룹화된 여러 앤드포인트들이 있다. 아래 예시는 Campagins라는 리소스에 다양한 엔드포인트들과 리소스 설명을 볼 수 있다. Campagins라는 리소스를 'Campagins는 Mailchimp목록에 이메일을 보내는 방법입니다. Campagins API 호출을 사용하여 Mailchimp계정에서 campaigns를 관리합니다.' 기술 문서에서 작성하는 개요와 같은 섹션이라고 보면 되지 않을까 싶다.
또 다른 예시로 카카오 디벨로퍼 문서에는 사전작업 과정을 요약해서 특정 API를 호출하기 전에 사전에 설정해야 할 항목들에 대해서 알려주고 있다.
추가로 여러 API문서들을 보다 보면 리소스를 지칭하는 용어가 다양하다는 것을 확인할 수 있다. 리소스라는 용어 외에도 API 호출, 엔드포인트, API 메서드, request, calls, object, calls, service와 같은 용어로 사용될 수 있다.
그럼 이제 위에서 제시한 예제를 토대로 리소스 설명을 작성해보고자 한다.
Before
새 엔드포인트는 /surfreport/{beachId}입니다. 이 엔드포인트는 서핑을 하려는 서퍼가 조수 및 파도와 같은 상태를 확인하고 해변에 나갈 수 있는지를 결정하는 것을 돕습니다. {beachId}는 사이트의 해변 목록에서 검색됩니다.
After
Surfreport
서핑 높이와 조수 및 바람을 포함한 서핑 조건에 대한 정보를 포함합니다. 또한 서퍼가 서핑을 하기에 적절한 조건인지에 대해 도움을 줄 수 있습니다.
위와 같이 간단하게 리소스 설명 작성해보았다. 다음에는 엔드포인트와 메서드를 정리해보고자 한다.
참고 사이트