API 문서화 공부하기 4 - 엔드포인트와 메서드

엔드포인트(Endpoint)는 리소스에 액세스 하는 방법을 의미하고 메서드(Method)는 리소스와의 상호작용을 의미한다. 동일한 리소스에는 일반적으로 경로와 메서드가 다르지만 동일한 리소스에 대해 다른 정보를 반환하는 엔드포인트가 있다. 

엔드포인트에는 "API 문서화 공부하기 3"에서 다루었던 리소스 설명과 유사하지만 간단한 설명이 존재한다. 또한 엔드포인트에는 모든 엔드포인트의 기본 경로가 아니라 리소스 URL의 마지막 경로만 표시된다. 

 

엔드포인트 예시

아래 이미지는 토스페이 결제 상태 확인에 대한 엔드포인트 예시이다. 

출처: 토스페이 API 가이드

API 문서의 대부분은 엔드포인트를 중심으로 작성되기 때문에 엔드포인트는 문서에서 강조 효과를 주는 방식으로 작성되어 있는 경우가 많다. 엔드포인트는 개발자가 요청을 수행하기 위해 구현하기 때문에 API 문서에서 중요한 요소 중에 하나이다. 

 

매개변수와 메서드 표시하기

매개 변수(Parameter)는 다음에 더 자세하게 다루겠지만 엔드포인트 경로에 매개변수가 있는 경우는 중괄호로 표시하는 것이 규칙으로 자리 잡고 있다. 아래 예시는 카카오 API문서의 예시이다. 

출처: 카카오 API 가이드

메서드는 엔드포인트 옆에 표시하는 것이 일반적이다. 거의 모든 API문서에 엔드포인트 옆에 메서드가 작성되어있는 것을 확인할 수 있다. 각 메서드에 대해서 간단하게 정리하자면 다음과 같다. 

• POST: 리소스 생성
• GET: 리소스 읽기
• PUT: 리소스 업데이트
• DELETE: 리소스 삭제
• PATCH: 기존 리소스를 일부 수정

 

엔드포인트 작성하기

엔드포인트를 설명할 때 엔드포인트만 나열하는 것을 권장하고 있다. 기본 경로와 엔드포인트를 모두 포함하는 전체 경로는 리소스 URL이라고 부른다. 예시 API 시나리오에서는 엔드포인트를 아래와 같이 작성했다. 전체 리소스 URL을 나열할 필요 없이 엔드포인트는 /surfreport/{beachID}로 적어주는 것을 권장한다. 

아래 예시에서도 전체 리소스 URL을 나열할 필요 없이 엔드포인트를 /v1/payments/{paymentKey}로 작성해준 것을 확인할 수 있다. 전체 리소스 URL은 소개 섹션이나 시작하기 문서 등에서 설명되는 경우가 많다고 한다. 

출처: 토스 페이먼츠 API 가이드

 

엔드포인트를 작성할 때는 동일한 리소스에 대해 여러 엔드포인트를 그룹화하는 것도 고려해야 한다. 아래 예시는 Mailchimp API 가이드이다. 계정 내보내기(Account Exports)의 엔드포인트를 다음과 같이 그룹화해서 나열하고 있다. 

출처: Mailchimp API 가이드

여기까지 다양한 API 가이드 문서에서 엔드포인트와 웹사이트를 어떻게 나타내고 있는지 확인해보았다. 그럼 실습 예제로 돌아와서 이전 포스팅에서 작성했던 리소스 설명과 함께 surfreport의 엔드포인트와 메서드를 작성해보면 다음과 같이 작성할 수 있다. 

Surfreport
서핑 높이와 조수 및 바람을 포함한 서핑 조건에 대한 정보를 포함합니다. 이 정보로 서퍼가 서핑을 하기에 적절한 조건인지를 알려줄 수 있습니다. 

EndPoint
GET Surfreport/{beachId}
beachId로 특정 해변의 서핑 조건을 가져옵니다. 

또는 엔드포인트에 대한 설명을 다음과 같이 적을 수도 있다. '특정 해변 ID의 서핑 조건을 가져옵니다.'