[TW] API 문서 톺아보기

Krew Insight

[TW] API 문서 톺아보기

celina.7 2021. 12. 14. 11:43

시작하며

안녕하세요. 카카오엔터프라이즈 테크니컬라이팅 팀의 Crystal(김유리), Sandy(차신영), July(김정인)입니다.
테크니컬라이팅 팀에서는 Kakao i 기술문서 사이트에 카카오엔터프라이즈가 개발하고 있는 다양한 기술들을 문서를 통해 전달하고 있는데요. 오늘은 Release Note 톺아보기에 이어 두 번째 시리즈로 API 문서를 샅샅이 톺아보도록 하겠습니다 :)

API(Application Programming Interface)는 '서버와 클라이언트가 데이터를 주고 받을 수 있도록 도움을 주는 매개체'라고 정의할 수 있습니다. API를 사용하기 위해서 사용자는 서버와 클라이언트 사이에 존재하는 몇 가지 약속을 따라야는데요. 메시지의 데이터 형식은 무엇이고, 글자수 제한이 있다면 몇 자인지, 어떤 방식으로 데이터가 전달되어야 하는지, 요청에 대한 결과는 어떤 형식으로 확인할 수 있는지 등과 같은 약속들을 예로 들 수 있습니다.

그럼 이 약속들은 어디서 확인할 수 있을까요? 이때 필요한 것이 바로 API 문서입니다. 저희 테크니컬라이팅 팀에서는 API 문서화에 대한 중요성을 인식하고, API 문서화 방법들과 당면한 과제들을 고민하고 있는데요. 오늘은 API 문서의 구성과 좋은 API 문서를 작성하기 위한 방법들을 살펴보도록 하겠습니다.

︱API 문서 구성

앞서 API 문서는 서버와 클라이언트간 특정 기술을 사용하기 위한 약속이라고 정의했는데요. '약속'이라는 개념에만 초점을 맞추다 보면 API 문서는 자칫 기능들만 나열된 API 명세서가 될 수 있습니다. API 문서화에서는 이런 API 명세서와 함께 API가 어떤 동작을 하는지, 어떤 목적에서 API가 탄생했는지, API를 사용하기 전에 수행해야 할 사전 작업이 있는지 등의 충분한 개념 설명이 담긴 '개요'와 API 사용 시퀀스를 설명한 '시작 가이드'도 준비하는 것이 좋은데요. 회사별 서비스나 기술 특성에 따라 API 문서 구성이나 문서명은 조금씩 다를 수 있지만, 오늘은 일반적으로 통용되는 API 문서 구성을 살펴보도록 하겠습니다.

# 개요

기술 문서의 서론은 독자들에게 본문의 요약, 작성 배경, 관련된 개념 등을 설명해 주는 역할을 합니다. 즉, 서론은 독자에게 글에서 말하고자하는 바를 전달하고, 글을 이해하기 위한 사전 지식 제공 등 독자가 글을 효과적으로 읽을 수 있도록 '가이드'하는 역할을 합니다. API 문서에도 이렇게 서론의 역할을 하는 섹션인 개요(Overview)가 필요한데요. 개요에는 API 소개, 개발 배경, 비즈니스 목적 등과 함께 공통 요청(Request) 및 응답(Response) 형식, 공통 에러 타입 등 전반적인 API 소개와 동작 설명을 포함할 수 있습니다.

• API 소개

API는 특정 목적을 가지고 탄생한 기능입니다. 따라서 API에 대한 간략한 소개, 개발 배경, 비즈니스 목적과 API의 장점을 소개하는 것이 좋은데요. 보통 내부 개발자들은 해당 API의 기획부터 개발까지 자세한 내용들을 잘 알고있겠지만, API 문서를 읽는 외부 독자들은 이런 내용을 알 수없습니다. 따라서, 단순히 API에 대한 기능 설명을 하는 것 보다는 API의 개발 배경, 비즈니스 목적, 장점 등을 포함한다면 외부 개발자는 API를 좀 더 명확히 이해하는데 도움이 될 것입니다.

• 공통 요청/응답 형식

개요에는 공통 요청(Request)과 응답(Response) 형식도 포함될 수 있는데요. 일반적으로 한 서비스의 API는 통일된 방식으로 API를 호출하며, 이때 API를 개발자가 어떤 방식으로 개발했느냐에 따라 문서의 구성이 달라집니다. 예를 들어 API 요청을 할 때 사용하는 데이터 형식을 ‘applicatoin/json’으로 제한했거나, 또는 ‘application/x-www-form-urlencode’로 표현된 데이터를 허용하는 개발자도 있는 것이죠.

응답도 마찬가지입니다. 어떤 개발자는 성공 혹은 실패 여부를 success 필드에서 성공인지 실패인지 설명하는 반면, 다른 개발자는 상태 코드를 통해 제공하는 경우도 있죠. 그리고 이런 점은 API 문서에 정확하게 반영되어야 합니다.

이렇게 개요에 해당 API의 공통된 요청과 응답 형식을 정리하면 독자는 API를 어떻게 접근할지 파악할 수 있습니다. 또한 동일한 내용을 각각의 API의 상단에 반복하여 작성하지 않아도 되기 때문에 가독성 있는 문서를 만들 수 있습니다.

• 공통 에러

만약 API 간 공통되는 에러 코드가 존재한다면, 문서의 한 섹션에 에러 코드를 모아두고 관리를 하는 것이 효율적입니다. 혹시 이런 에러 코드를 모아둘 섹션이 마땅치 않다면, 이를 개요 문서에 정리하고 각 API에 공통 에러 테이블을 링크로 연결하는 것은 어떨까요? 문서의 한 섹션에 공통 에러를 제공하면 각 API에 에러 코드를 각각 추가하지 않아도 되고, 변경도 한 곳에만 하면 되니 테크니컬라이터 입장에서는 문서 정합성 유지에도 큰 도움이 됩니다.

# 시작하기

아무리 API 레퍼런스가 잘 작성되었다 할지라도, 해당 API를 어떤 순서로 어떻게 사용하는지를 설명하는 개발 가이드가 없다면 어떨까요? 일회성으로 API를 한번 호출하고 끝나면 편하겠지만, 많은 경우에 특정 API를 호출하기 전에 인증 API 등의 선제적 API를 호출해야 한다거나, 관리자 사이트 등에서 인증키 정보 등을 획득해야 할 경우, 이런 일련의 시작하기(Getting Started) 과정이 필요합니다. 하지만, API 문서에서 시작하기 내용이 누락된 경우가 실제로 많이 존재하는데요. 고객사에서 API 문서를 요청했을 때 Swagger 등의 링크나 API 명세서만 제시하는 경우가 대표적입니다. Swagger는 훌륭한 API 도구이지만, 사용 순서를 문서화 할 수 있는 공간에 제약이 있기 때문에 Swagger 링크와는 별개로 별도의 문서에 API의 사용 순서를 설명하는 시작 가이드를 제작하는 것이 바람직합니다.

• 사전 작업

API 사용에 앞서 보통 계정을 등록하거나 또는 API Key 등록과 인증하는 등의 사전 작업이 필요할 수 있습니다. 예를 들어 카카오워크 Web API를 이용하여 Bot을 생성할 때, 자동으로 부여받은 인증키(App Key)를 통해 어떤 Bot에서 받은 요청인지 인증 및 권한을 검사하는 작업이 필요합니다. 따라서 시작 가이드에는 사전에 인증키(App key)를 어떻게 발급할 수 있고 어떤 용도로 사용되는지 상세히 설명되어야 합니다.

• API 사용 시퀀스

API에도 사용 시퀀스가 존재할 수 있습니다. 예를 들어 카카오워크 Bot을 생성한다고 했을 때, 위의 사전 작업 이후에 특정 멤버를 조회하고, 해당 멤버와의 채팅방을 생성하고, 메시지를 전송하는 일련의 시퀀스가 존재하는데요. 이런 사용 시퀀스가 없다면 외부 개발자들은 스스로 탐구하는 자세로 여러 API를 순서에 맞지 않게 호출해서 원하는 결과를 얻지 못할 수도 있습니다. 따라서 API 사용 시퀀스가 존재한다면 넘버링 형식으로 시퀀스를 정리하는 것이 좋습니다.

# API 레퍼런스

앞서 'API는 특정 기술을 사용하기 위한 약속이다' 라고 했는데요. 이 약속들은 보통 요청 방식, 요청 파라미터 유형, 파라미터의 필수 여부 등을 의미합니다. 개발자는 이 약속들을 확인하고 용도에 맞게 코드를 작성해야 합니다. 앞서 이야기한 카카오워크 Bot에서는 멤버 조회, 채팅방 생성, 메시지 전송 등의 API를 사용해야 하는데요. 이런 API 별 요청과 응답을 정리해 놓은 문서가 바로 API 레퍼런스인데요. API 레퍼런스는 대게 요청(Request)와 응답(Response)로 구성됩니다.

• 요청 (Request)

먼저 API 요청을 제대로 하기 위해서는 특정 항목들을 일정 포맷에 따라 호출해야 하는데요. API 요청을 문서로 정리할 때 저희는 Request Syntax, Request Header, Request Element로 구분하고, 모든 서비스에 이 구성을 적용하고 있습니다.

① Request Syntax

Request Syntax는 API의 형태, 구조에 대한 정의를 나타냅니다. API가 어떤 메서드를 사용하고, 요청 URL의 형태는 무엇인지, 그리고 코드 예제가 함께 제공되어야 합니다.

② Request Header

Request Header는 요청에 대한 추가 정보를 담고 있는 부분입니다. 예를 들어 메시지의 총 길이(Content-Length), 형식(Content-Type) 등이 Header에 포함될 수 있는데요. 앞에서 발급받은 인증을 위한 정보를 Header에 작성하기도 합니다.

Header	설명
Host	요청이 전송되는 URL
User-Agent	요청을 보내는 클라이언트에 대한 정보 ex) 웹브라우저 정보
Content-Type	요청이 보내는 메시지 타입 ex) application/json
Content-Length	요청하는 메시지의 길이

③ Request Element

Request Element는 해당 요청의 실제 메시지/내용이 해당됩니다. Request Element에는 API를 요청하기 위한 파라미터와 파라미터의 유형, 필수 여부와 설명, 제약 사항 등이 제공되어야 합니다. 간혹 Element가 없는 요청도 있는데요. 대표적으로 정보를 불러올 때 사용하는 GET 메서드에서 Element가 없는 요청이 나타나기도 합니다.

• 응답 (Response)

응답은 API 요청에 대한 결과값을 의미합니다. 예를 들어 특정 채팅방에 메시지를 전송했을 때 메시지가 정상적으로 전송되었는지 전송 결과를 확인할 수 있습니다.

① Response Element

Response Element에서는 API 요청에 대한 결과값을 확인할 수 있습니다. 요청한 API의 메서드에 따라 응답 형태는 달라질 수 있는데요. POST와 같이 값을 Body에 실어보낼 때는 해당 값이 잘 저장되었는지, 전달되었는지를 나타내는 성공여부를 나타내기도 하고, GET과 같이 특정 정보를 조회하거나 받아올 때는 값들을 코드로 확인할 수 있거나 자동적으로 다운로드 되기도 합니다.

Response Element에는 필드, 필드 유형, 필수 여부와 설명이 제공되어야 합니다. 만약 개발자가 특정 고객 정보에서 이름과 고객의 메일 주소를 가져오고 싶은 경우라면, 이름과 메일 주소의 필드 이름이 각각 무엇인지 알아야겠죠?

︱좋은 API 문서 작성 Tips

앞서 나온 API 문서 구성 요소들을 바탕으로 독자에게 더 친숙한 API 문서를 작성하는 방법은 무엇일까요? 저희 테크니컬라이팅 팀에서는 여러 자료를 비교 분석하여 API 문서 작성에 대해 스터디하고 있는데요. API 문서화와 관련된 몇 가지 Tip을 공유해 드리겠습니다.

# API 리스트업

여러분은 ‘카카오워크 Bot’ 하면 어떤 기능이 떠오르시나요? Bot을 이용해 회원들에게 메시지를 보낼 수도 있고, Bot이 회원들의 정보를 가져올 수도 있고, 특정 워크스페이스에 정보를 조회할 수도 있겠죠? 카카오워크 Web API 레퍼런스에 담긴 API만 해도 18개인데요. 이처럼 하나의 API 레퍼런스 안에는 다양한 API가 제공됩니다. 사실 개발자는 모든 API를 다 사용하기보다는 개발하고자 하는 기능에 맞는 API를 선택해서 사용합니다. 이때 API를 종류에 따라 구분하고 한눈에 리스트업한 후 링크를 활용해 바로가기를 하면 API 사용에 용이합니다.

# 시각적 UI 활용

API 문서를 몇 번 읽어보신 분들은 아시겠지만 API문서는 파라미터 설명, 예제 코드, API 설명이 반복되는 글입니다. 이러한 글은 자칫하면 반복적인 나열 등 텍스트로만 작성되어 독자들을 지루하게 하는데요. 따라서 테이블 계층화나 코드 블럭 등 시각적인 요소들을 활용해 직관적으로 글을 작성하는 것이 필요합니다.

• 테이블 계층화

요청 또는 응답에서 사용되는 파라미터는 파라미터의 이름, 타입, 필수여부, 설명을 담고 있습니다. 이를 한줄씩 나열하면 파라미터가 줄글로 길어지기 마련인데요. 따라서 구분을 쉽게하기 위해 테이블로 작성하고 테이블을 계층화하는 것은 어떨까요? 응답 파라미터 요소 중에 파라미터 값 아래에 세부 파라미터들이 생기는 경우가 있는데, 이때 계층화를 이용하면 전체적인 API의 구성을 직관적으로 확인할 수 있습니다.

• 코드블럭 활용

API를 사용할 때 파라미터의 이름이나 필수적으로 작성해야하는 값 등 고정된 값들은 그대로 작성되어야 하는데요. 따라서 고정된 값들을 작성할 경우, 코드 블록을 적용한다면 어떨까요? 독자들은 ‘이 값은 그대로 입력해야 하는 고정값’이라는 개념을 보다 쉽게 이해할 수 있게 될 것 입니다. 그리고 독자에게 일관된 메시지를 전달하기 위해, 이런 규칙은 모든 API에 일괄적으로 적용하는 것이 좋습니다. 또한 에러 코드 등 강조가 필요한 경우에도 코드 블록을 사용하면 좋은데요. 저희는 고정 입력값과 에러 코드에 코드블록을 적용하고 있는데요. 회사별 스타일 가이드에 따라 코드 블록을 적용할 항목들을 정했다면, 이를 일괄적으로 문서에 반영하는 것이 좋겠죠?

# 지속적인 업데이트

API 레퍼런스를 게시했다고 해서 API 문서 작업이 끝난 것은 아닙니다. API는 기술의 변화와 사용자의 피드백을 반영하여 지속적으로 업데이트되고 있는데요. API는 업데이트되었는데, 레퍼런스가 그대로일 경우 문서는 뒤떨어진(out of date) 문서가 됩니다. 사용자 입장에서는 문서의 지시를 분명히 따랐음에도 불구하고 API를 원하는 대로 사용할 수 없거나 잘못된 결과가 나올 수 있으니 지속적인 업데이트가 필요합니다.

마치며

지금까지 API 레퍼런스 구성부터 API 문서 작성 Tip까지 살펴보았는데 어떠셨나요?
API 문서는 개발자가 API를 사용하기 위한 모든 것을 담고 있는 문서인데요. 개발자 입장에서는 부정확하고 신뢰성 떨어지는 문서로 인하여 시간을 낭비하는 일이 발생해서는 안될 것 입니다. 이번 포스팅에서 API 문서화의 구성과 작성 방향을 이해하는데 도움 되셨길 바라며, 저희의 다음 톺아보기 시리즈도 기대해 주세요. 감사합니다 :)

📍 테크니컬 라이팅 관련 글 더보기

✓ 퇴고의 기술
✓ 올바른 동사 사용 가이드
✓ 기술문서의 쉼표 사용 가이드라인
✓ Release Note 톺아보기
✓ 개요 작성의 중요성
✓ 개발자들을 위한 테크니컬 라이팅 10계명
✓ 목차의 중요성
✓ 기술 문서 작성 5단계
✓ 테크니컬 라이팅 4대 원칙
✓ 기술 문서 쉽게 쓰기 지침
✓ 언어학 관점에서의 기술문서 가독성 향상 전략
✓ 카카오 i 기술문서 사이트 여정, 그리고 벌써 한 달
✓ Technical Writer에서 Technical Communicator로...
✓ [KREW INSIDE] AI 서비스의 기술 문서를 책임지는 사람들, 테크니컬 라이터