API(Application Programming Interface)
API(Application Programming Interface)는 '서버와 클라이언트가 데이터를 주고 받을 수 있도록 도움을 주는 매개체' 라고 정의할 수 있다. 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 를 좀 더 명확히 이해하는데 도움이 될 것이다.
❓공통 요청/응답 형식
개요에는 공통 요청(Reqeust)과 응답(Response) 형식도 포함될 수 있다. 일반적으로 한 서비스의 API는 통일된 방식으로 API를 호출하며, 이때 API를 개발자가 어떤 방식으로 개발했느냐에 따라 문서의 구성이 달라진다. 예를 들어 API 요청을 할 때 사용하는 데이터 형식을
"apllication/json"으로 제한했거나, 또는 "application/x-www-form-urlencode"로 표현된 데이터를 허용하는 개발자도 있다는 것이다.
응답도 마찬가지이다. 어떤 개발자는 성공 혹은 실패 여부를 success 필드에서 성공인지 실패인지 설명하는 반면, 다른 개발자는 상태 코드를 통해 제공하는 경우도 있다. 그리고 이런 점은 API 문서에 정확하게 반영되어야 한다.
이렇게 개요에 해당 API의 공통된 요청과 응답 형식을 정리하면 독자는 API를 어떻게 접근할지 파악할 수 있다. 또한 통일한 내용을 각각의 API의 상단에 반복하여 작성하지 않아도 되기 때문에 가독성 있는 문서를 만들 수 있다.
❓공통 에러
만약 API 간 공통되는 에러 코드가 존재한다면, 문서의 한 섹션에 에러 코드를 모아두고 관리를 하는 것이 효율적이다. 혹시 이런 에러코드를 모아둘 섹션이 마땅치 않다면, 이를 개요 문서에 정리하고 각 API에 공통 에러 테이블을 링크로 연결하는 것이 좋을 것이다.
문서의 한 섹션에 공통 에러를 제공하면 각 API에 에러 코드를 각각 추가하지 않아도 되고, 변경도 한 곳에서만 하면 되니 테크니컬라이터 입장에서는 문서 정합성 유지에도 큰 도움이 된다.
tip. 테크니컬 라이터는 사용자가 제품을 쉽게 사용할 수 있게 돕거나, 위험한 상황에 미리 대비할 수 있게 알려주거나, 문제가 생겼을 때 해결하는 방법을 가이드하는 문서를 쓰는 사람이다
# 시작하기
아무리 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 인증
카카오워크의 WebAPI는 Bot 생성 시에 자동으로 부여받은 인증키(App Key)를 HTTP 요청(Request)의 Authoriztion 헤더를 통해 전달하여 어떤 Bot에서 받은 요청인지 인증 및 권한 검사를 수행한다.
- API 사용 시퀀스
API에도 사용 시퀀스가 존재할 수 있다. 예를 들어 카카오워크 Bot을 생성한다고 했을 때, 위의 사전 작업 이후에 특정 멤버를 조회하고, 해당 멤버와의 채팅방을 생성하고, 메세지를 전송하는 일련의 시퀀스가 존재한다. 이런 사용 시퀀스가 없다면 외부 개발자들은 스스로 탐구하는 자세로 여러 API를 순서에 맞지 않게 호출해서 원하는 결과를 얻지 못할 수도 있다.
따라서, API 사용 시퀀스가 존재한다면 넘버링 형식으로 시퀀스를 정리하는 것이 좋다.
# API 레퍼런스
앞서 "API는 특정 기술은 사용하기 위한 약속이다" 라고 했는데, 이 약속들은 보통 요청 방식, 요청 파라미터 유형, 파라미터 필수 여부 등을 의미한다. 개발자는 이 약속들을 확인하고 용도에 맞게 코드를 작성해야한다. 앞서 이야기한 카카오워크 Bot에서는 멤버 조회, 채팅방 생성, 메시지 전송 등의 API를 사용해야한다.
이런 API별 요청과 응답을 정리해 놓은 문서가 바로 "API 레퍼런스"이다.
API레퍼런스는 대게 요청(Reqeust)와 응답(Response)로 구성된다.
- 요청 (Reqeust)
먼저 API 요청을 제대로 하기 위해서는 특정 항목들을 일정 포맷에 따라 호출해야 한다. API 요청을 문서로 정리할 때 저희는 Reqeust, Syntax, Request Header, Request Element 로 구분되고, 모든 서비스에 이 구성을 적용하고 있다.
Tip. 성공적인 API 요청을 위한 것
- 어떤 API 요청 방식을 가지고 있는지
- 요청이 실행되는 곳은 어디인지
- API 요청을 하기 위해 별도의 인증 방식이 있는지
- 어떤 채팅방에 메시지를 전송할 것인지
- 전송할 채팅 메시지 내용은 무엇인지
- 메시지를 작성할 때 글자수는 몇자로 제한 되는지
- 메시지 전송 시 형태는 어떻게 되는지
- API 요청을 별도로 테스트할 수 있는지
1️⃣ Request Syntax
Request Syntax는 API의 형태, 구조에 대한 정의를 나타낸다. API가 어떤 메서드를 사용하고, 요청 URL의 형태는 무엇인지, 그리고 코드 예제가 함께 제공되어야 한다.
2️⃣ Request Header
Request Header는 요청에 대한 추가 정보를 담고 있는 부분이다. 예를 들어 메시지의 총 길이(Content-Length), 형식(Content-Type) 등이 Header에 포함될 수 있다. 앞에서 발급받은 인증을 위한 정보를 Header에 작성하기도 한다.
3️⃣ Request Element
Request Element 는 요청의 실패 메시지/내용이 해당된다. Request Element에는 API를 요청하기 위한 파라미터와 파라미터의 유형, 필수 여부와 설명 제약 사항 등이 제공되어야 한다. 간혹 Element가 없는 요청도 있는데, 대표적으로 정보를 불러올 때 사용하는 GET 메서드에서 Element가 없는 요청이 나타나기도 한다.
- 응답 (Response)
응답은 API 요청에 대한 결과값을 의미한다. 예를 들어 특정 채팅방에 메시지를 전송했을 때 메시지가 정상적으로 전송되었는지 전송 결과를 확인할 수 있다.
1️⃣ Response Element
Response Element 에서는 API 요청에 대한 결과값을 확인할 수 있다. 요청한 API의 메서드에 따라 응답 형태가 달라질 수 있다.
POST와 같이 값을 BODY에 싫어 보낼 때는 해당 값이 잘 저장되었는지, 전달되었는지를 나타내는 성공여부를 나타내기도 하고, GET과 같이 특정 정보를 조회하거나 받아올 때는 값들을 코드로 확인할 수 있거나 자동적으로 다운로드 되기도 한다.
Response Element에는 필드, 필드 유형, 필수 여부와 설명이 제공되어야 한다. 만약 개발자가 특정 고객 정보에서 이름과 고객의 메일 주소를 가져오고 싶은 경우라면, 이름과 메일 주소의 필드 이름이 각각 무엇인지 알아야 한다.
좋은 API 문서 작성 Tips
# API 리스트업
API 모든 기능을 리스트업 해서 링크를 활용하여 바로가기를 하면 API 사용에 용이하다.
#시각적 UI 활용
API 문서를 몇번 읽어보면 알겠지만 API 문서는 파라미터 설명, 예제 코드, API 설명이 반복되는 글이다.
이러한 글은 자칫하면 반복적인 나열 등 텍스트로만 작성되어 독자들을 지루하게 한다. 따라서 테이블 계층화나 코드 블럭 등 시각적인 요소들을 활용하여 직관적으로 글을 작성하는것이 필요하다
- 테이블 계층화
요청 또는 응답에서 사용되는 파라미터는 파라미터의 이름, 타입, 필수 여부, 설명을 담고있다. 이를 한줄씩 나열하면 파라미터가 줄글로 길어지기 마련이다. 따라서 구분을 쉽게 하기 위해서 테이블로 작성하고 테이블을 계층화 하는것이 편리하다.
응답 파라미터 요소 중에 파라미터 값 아래에 세부 파라미터들이 생기는 경우가 있는데, 이 때 계층화를 이용하면 전체적인 API의 구성을 직관적으로 확인할 수 있다.
- 코드블럭 활용
API를 사용할 때 파라미터의 이름이나 필수적으로 작성해야하는 값 등 고정된 값들은 그대로 작성되어야 한다.
따라서 고정된 값들을 작성할 경우, 코드 블럭을 적용하는 것이 좋다. 독자들은 "이 값은 그대로 입력해야 하는 고정 값" 이라는 개념 보다 쉽게 이해될 것이다. 그리고 독자에게 일관된 메시지를 전달하기 위해 이런 규칙은 모든 API에 일괄적으로 적용하는것이 좋다. 또한 에러 코드 등 강조가 필요한 경우에도 코드 블록을 사용하면 좋다.
# 지속적인 업데이트
API 레퍼런스를 게시했다고 해서 API 문서 작업은 끝난 것이 아니다. API 기술의 변화와 사용자의 피드백을 반영하여 지속적으로 업데이트 되고 있다. API는 업데이트 되었는데, 레퍼런스가 그대로일 경우 문서는 뒤떨어진 문서가 된다.
사용자 입장에서는 문서의 지시를 분명히 따랐음에도 불구하고 API를 원하는대로 사용할 수 없거나 잘못된 결과가 나올 수 있으니 지속적인 업데이트가 중요하다.
참고 사이트
'CS > 백엔드 로드맵 따라가기' 카테고리의 다른 글
| [백엔드 로드맵] 브라우저와 그 작동원리 & DNS와 그 작동원리 (0) | 2022.04.17 |
|---|---|
| [백엔드 로드맵] 인터넷의 작동원리 & HTTP란? (0) | 2022.04.17 |
| [백엔드 로드맵] 백엔드 개발자가 되기위한 여행 (0) | 2022.04.17 |
