API 문서화 공부하기 6 - 요청 예시

요청 예시 살펴보기 

요청 예시에는 엔드포인트를 사용하는 샘플 요청이 포함되어 있으며 일부 매개변수를 보여준다. 요청 예제는 모든 매개변수를 표시하지는 않지만 매개변수를 가능한 많이 보여주는 것이 좋다.

지난번 살펴본 토스페이 API 가이드에서는 오른쪽에 샘플 요청과 응답을 보여주고 있다. 

출처: 토스페이 API 가이드

다양한 언어들로 요청 예제를 제공하고 있지만 위 예시는 curl 형식의 예제이다. 일반적으로 curl을 사용하여 샘플 요청을 표시한다. curl은 요청에 필요한 헤더 정보와 요청과 함께 사용된 방법을 보여준다. 

✋curl이란?
다양한 매개변수와 메서드를 사용하여 HTTP 요청을 실행할 수 있는 command line이다. curl을 사용할 때는 curl입력 후에 다음에 출력을 받아올 URL을 추가하여 작성한다. 
HTTP에는 헤더가 존재하는데 curl에서는 -H 옵션을 통해 요청에 헤더 값을 추가할 수 있다. curl에는 -다양한 옵션들이 존재한다. (옵션에 대해서는 다음에 정리해야겠다)

다음은 카카오 API 가이드 예시이다. curl에 백 슬래시를 추가하여 각 매개변수를 자체행으로 분리해서 작성했다. 

출처: 카카오 API 가이드

매개변수가 많은 경우에는 여러 요청 예제를 포함하는 것이 좋다. 다음은 Confluence의 Places API 예제이다. 

출처: Places API

여기에 사용될 수 있는 매개변수는 17개나 된다. 이 경우에는 모든 매개변수를 다 사용할 확률은 낮기 때문에 매개변수를 조합해 몇 가지 샘플을 보여주고 있다. 

출처: Places API

 

다양한 언어로 요청하기 

REST API는 언어에 구애받지 않지만 개발자는 Java, Ruby, Python 등 다양한 언어로 개발을 한다. 그래서 일부 API문서에는 다양한 언어로 요청 예시를 제공하고 있다. 토스 페이에서도 상단 탭에서 언어를 선택할 수 있도록 되어있다. 다양한 언어로 요청 예시를 제공하면 개발자는 curl요청을 다른 프로그래밍 언어로 변환할 필요 없이 필요한 코드를 복사해서 사용할 수 있다. 

출처: 토스페이 API 가이드

다른 프로그래밍 언어로 REST요청을 만드는 패턴이 공통 템플릿을 따르기 때문에 코드 샘플을 자동으로 생성할 수 있다고 한다. 코드 예제를 자동으로 생성하는 다양한 도구들이 있지만 지난번 살펴보았던 Postman으로도 코드 샘플을 자동으로 생성할 수 있다.  

출처: 본인

출처: 본인

여기서 주의해야 할 점은 예제 코드가 잘 작동하는지 확인해야 한다고 말한다. 개발자와 함께 코드 샘플을 검토하는 것이 중요하다. 대부분의 경우에 개발자는 문서의 코드 샘플을 제공하고 TW가 코드 샘플에 대해 간략하게 설명하는 역할을 수행한다고 한다. 

여기까지 살펴봤으면 예제에서 제시했던 Surfreport의 요청 예시를 작성해보자

---

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

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

Path parameter

Name	Description
{beachId}	해변의 ID값 {beachId}는 사이트의 해변 목록에서 검색됩니다.

Query string parameter

Name	Type	Required	Description
days	Integer	X	응답에 포함할 일 수입니다. 기본값은 3입니다. 최대로 볼 수 있는 일 수는 7입니다.
time	Integer UTC의 Unix형식	X	시간을 포함하면 현재 시간만 응답으로 반환합니다.
units	string	X	측정 단위입니다. metric(야드 파운드 법)과 imperial(미터법) 단위를 사용할 수 있습니다. 값이 없으면 standard 단위가 기본값으로 적용됩니다.

Sample Request

curl -I -X GET "https://api.openweathermap.org/com/surfreport/{beachId}?&days=2&units=metrics&hour=1400"

---

참고하며 공부하고 있는 사이트에서도 Surfreport예제에 대한 답안을 제시해 주지만 Sample Request가 예제와 다르게 작성되어 있는 것 같다. 하지만 답을 알 수 없어서 답답하다😂 공부하다 보면 답을 알 수 있겠지..