API 문서화 공부하기 7 - 응답 예제와 응답 스키마

이사 준비로 어영부영 6월이 지나갔다. 이사를 무사히 마쳤으니 다시 열심히 포스팅해야겠다! 😁

---

응답 예제와 응답 스키마

응답 예제는 요청 예제의 샘플 응답을 보여준다. 응답 예제는 모든 매개변수를 포괄하지는 않지만 요청 예제에서 전달된 매개변수와 일치해야 한다. 응답을 통해 개발자는 리소스에 원하는 정보, 형식 및 해당 정보가 구조화되고 레이블이 지정되는 방식이 무엇인지 알 수 있다. 

응답에 대한 설명을 응답 스키마라고 한다. 응답 스키마는 반환될 수 있는 각 속성, 각 속성에 포함된 내용, 값의 데이터 형식, 구조 및 기타 세부 정보를 나열하여 보다 포괄적인 방식으로 응답을 문서화한다.

 

응답 스키마 살펴보기 

응답 예제와 응답 스키마의 차이는 무엇일까? 응답 예제는 요청 예제와 일치해야 한다. 요청 예제가 가능한 모든 매개변수를 포함하고 있는 것처럼 응답 예제는 가능한 모든 반환 정보를 포함하는 것이 좋다. 그러나 응답 스키마는 응답에서 반환되는 가능한 모든 속성을 포함한다. 응답 스키마는 다음 정보를 제공한다.

• 각 속성에 대한 설명
• 각 속성에 대한 데이터 유형 정의 
• 각 속성이 필수인지 선택인지 여부 

응답 예시가 직관적일 경우에는 아래 예시처럼 응답 스키마를 생략하기도 한다. 저자는 개발자들이 많은 응답이 무엇을 의미하는지 모르는 경우가 많기 때문에 설명된 응답과 함께 제시하는 것을 권장하고 있다. 또한 응답 예제에서 값이 적절한 예시로 들어갔는지 확인해야 한다고 한다. 또한 당연하게도 실제 고객 데이터가 포함되어서는 안 된다. 

출처: 트위터 API가이드

응답 스키마에 대한 문서 형식은 API문서의 가장 어려운 측면 중에 하나라고 말한다. 일반적으로는 아래 예시처럼 표를 사용해서 작성하고 있다. 또 다른 API문서에서는 표가 아닌 문장 형식으로 개발자에게 응답 항목을 설명하듯이 작성하기도 한다. 아래 예시에서도 표를 사용해 속성에 대한 설명, 데이터 유형 정의, 속성의 필수 또는 선택인지 여부를 설명하고 있다. 

출처: 카카오 디벨로퍼 API 가이드

 

응답 예제 살펴보기

응답 예제와 응답 스키마를 어떻게 표현할지도 고민해봐야 하는데 일부 API문서에서는 응답 예제를 오른쪽 열에 배치하여 리소스 설명 및 매개 변수를 보면서 응답 예제를 볼 수 있도록 했다. 두 가지를 동시에 볼 수 있다는 개념이다. 하지만 응답 예제와 설명이 일치하지 않으면 보는 사람의 초점이 분산되고 결국 사용자는 더 많은 스크롤을 하게 된다고 말한다. 

출처: 토스페이 API가이드

(여기서 궁금한 점은 이제까지 본 API가이드 문서는 응답과 응답 예제가 비교적 순서대로 작성되어있는 것을 볼 수 있는데 왜 토스 페이에서는 순서가 다른 경우가 있는 걸까? 직접 사용해보지는 않아서 이 순서에 이유가 있는 건지 아직은 파악할 수 없지만 궁금하다🤔)

또 다른 응답 예제는 MYOB의 API가이드 문서이다.  3열 디자인과 동일하게 오른쪽에 응답 예제가 있다. 설명과 응답 예제를 동시에 볼 수 있다는 것은 동일하다. 그러나 이 구조에서 응답 설명을 확인하려면 마우스 커서를 응답 위로 가져가야 나타난다. 동시에 응답 예제에는 해당 응답이 강조 처리돼서 확인하기가 쉽다.

이 방식은 관심 있는 항목에만 마우스 커서를 올려놓고 확인하기 때문에 (팝오버 방식) 보기에는 깔끔해 보일 수 있다.  하지만 문서화 관점에서 보기에는 사용자가 값을 확인하기 위해 하나씩 마우스 커서를 올려놔야 한다는 번거로움이 있다. 

출처: MYBOX API가이드

 

중첩 객체 표현하기

중첩 객체가 있는 경우 슬래시로 구분을 하거나 열을 나눠서 표현하기도 한다.  위에서 살펴본 MYBOX API가이드에서는 중첩 객체를 표에서 들여 쓰기로 표현해주었다. 반면에 드롭박스 API 가이드에서는 중첩을 슬래시로 나타낸다. 아래 예시에서 name_details는 여러 객체 수준을 나타내고 있다. 

출처: 드롭박스 API가이드

 

또 다른 예시로 토스 페이 API가이드를 살펴보면 중첩 객체의 색상을 다르게 해서 구분해주었다. 반면에 카카오 디벨로퍼 API가이드에서는 중첩 객체에 대한 응답을 별도의 표로 제시하고 있다.  중첩 객체를 표현하는 방식에도 다양한 방법이 존재함을 알 수 있다. 

출처: 토스 페이 API가이드 

 

출처: 카카오 디벨로퍼 API가이드 

 

이제까지 살펴본 내용을 바탕으로 예제의 응답 예제와 응답 스키마를 작성해보았다. (예제를 처음부터 끝까지 작성하기에 이제 너무 길어져서 응답 스키마와 응답 예제 부분만 작성했다.)

---

Response

Name	Type	Description	Required
beach	string	요청한 해변 ID를 기반으로 선택한 해변을 불러옵니다.  해변 이름은 국립공원관리청 지오데이터베이스에 설명된 공식 이름입니다.	O
{day}	object	선택한 요일 응답에 최대 3일이 반환됩니다.	O
{time}	string	조건에 대한 시간 이 항목은 요청에 시간 매개변수를 포함하는 경우에만 포함됩니다.	X
{day}/{time}/tide	Integer	특정 날짜 및 시간에 대한 해변의 조수	O
{day}/{time}/wind	Interger	해변의 풍속	O
{day}/{time}/watertemp	Interger	물의 온도  지정한 단위에 따라 화씨 또는 섭씨로 반환됩니다.	O
{day}/{time}/surfeight	Interger	파도의 높이 지정한 단위에 따라 피트 또는 센티미터로 반환됩니다. 3피트의 서핑 높이는 서핑에 필요한 최소 크기 입니다. 서핑 높이가 10피트를 초과하면 서핑을 권장하지 않습니다.	O
{day}/{time}/recommendation	String	서핑 권장 응답 세 가지 응답이 가능합니다. 1)"서핑하기 좋은 날 입니다!", 2)"서핑 조건은 괜찮지만 날씨가 좋지는 않습니다." , 3)"서핑하기 좋은 날이 아닙니다".	O

 

Sample Response

{
    "surfreport": [
        {
            "beach": "Santa Cruz",
            "monday": {
                "1pm": {
                    "tide": 5,
                    "wind": 15,
                    "watertemp": 60,
                    "surfheight": 5,
                    "recommendation": "Go surfing!"
                },
                "2pm": {
                    "tide": -1,
                    "wind": 1,
                    "watertemp": 50,
                    "surfheight": 3,
                    "recommendation": "Surfing conditions are okay, not great"
                }
                ...

            }
        }
    ]
}

---

여기까지 SurfReport 엔드포인트에 대한 문서화 작업을 마쳤다! 과정을 따라 공부하고 다양한 예시들을 찾아보다 보니 이전보다 아주 아주 조금 API문서에 대한 이해도가 높아졌다는 생각이 든다. 😅다음 포스팅에서는 이제까지 작성한 예제를 통합해서 Markdown으로 작성해보고 더 추가하거나 고쳐야 할 부분이 있는지 살펴보려고 한다.