[API] API 문서 작성 요령 익히기

회사에서 API 를 구현하며 swagger와 API 명세서를 작성하고 있는데,

기본적인 작성 방법과 요령을 인지해두는 것이 좋을 듯 해서 카카오 테크니컬라이팅 팀에서 작성한 API 문서 톺아보기 게시글을 참고하여 정리해보고자 한다.

---

API(Application Programming Interface)

서버와 클라이언트가 데이터를 주고 받을 수 있도록 도움을 주는 매개체

일반적으로 정해야 하는 규칙

→ 메시지의 데이터 형식은 무엇이고, 글자수 제한이 있다면 몇 자인지, 어떤 방식으로 데이터가 전달되어야 하는지, 요청에 대한 결과는 어떤 형식으로 확인할 수 있는지

API는 단순 기능들을 나열한 명세서가 아니라,

어떤 동작을 하고, 어떤 목적을 위한 것인지, API 사용 전 수행할 사전 작업이 있는지 등의 충분한 설명이 담긴 개요와 API 사용 시퀀스를 설명한 시작 가이드도 있으면 좋다.

회사마다 구성이나 문서명은 다를 수 있으나, 일반적으로 통용되는 API 구성을 알아보자.

 

 

개요

기술문서의 서론. 본문의 요약, 작성 배경, 관련 개념을 설명해주는 역할.

Overview. API 소개, 개발배경, 비즈니스 목적 등과 함께 Request 및 Response 형식, 공통 에러 타입 등 전반적인 API 소개와 동작 설명을 포함한다.

 

• API 소개

API에는 특정한 목적이 있다. 그에 대한 간략 소개, 개발 배경, 비즈니스 목적과 장점을 소개하는 것이 좋다.

외부 독자는 개발 내용을 모르기 때문에 API에 대한 기능 설명 보다는 외부 개발자의 입장에서 설명.

 

• Request/Response

일반적으로 한 서비스의 API는 통일된 방식으로 API 호출.

예를 들어, 요청시 데이터 형식을 ‘applicatoin/json’으로 제한했거나, 또는 ‘application/x-www-form-urlencode’로 표현된 데이터를 허용하는 개발자도 있다.

응답도 마찬가이지다. 어떤 개발자는 성공, 실패 여부를 success 필드에서 설명하는 반면, 다른 개발자는 상태 코드를 통해 제공하는 경우도 있다. 이런 점이 문서에 반영되어야 한다.

이 내용을 개요에 정의해준다면 동일한 내용을 각각의 API에 반복하여 작성하지 않아도 되므로 가독성이 증가한다.

 

• 공통에러

API간 공통되는 에러 코드가 존재한다면 문서의 한 섹션에 에러코드를 모아두고 관리하는 것이 효율적이다.

이런 공간이 따로 없다면, 개요 문서에 정리하고 각 API에 공통 여러 테이블을 링크로 연결하거나 하자.

 

시작하기

만든 API를 어떤 순서로 어떻게 사용하는지를 설명하는 개발 가이드가 있어야한다.

일회성 API 호출이면 몰라도, 특정 API를 선제적으로 먼저 호출해야한다거나, 인증키 정보등을 획득해야 할 경우에는 일련의 시작하기 과정이 필요하다.

고객사에서 API 문서를 요청했을 때, Swagger 등의 링크나 API 명세서만 제시하는 경우가 많다.

Swagger는 훌륭한 도구이지만, 사용 순서를 문서화 할 수 있는 공간에 제약이 있기 때문에 Swagger와는 별개로 문서에 API 사용 순서를 설명하는 시작 가이드를 제작하는게 바람직하다.

→ Swagger : 내부 개발자끼리 공유용으로는 괜찮음.

→ 다만 외부 고객이 사용해야하는 Open API를 제작한다면 더욱 자세한 명세서가 따로 필요.

 

• 사전 작업

API 사용에 앞서 보통 계정을 등록하거나 API Key 등록과 인증이 필요한 작업이 있을 수 있다.

예를 들어, 카카오 워크 Web API를 사용해 Bot을 생성한다면, 자동으로 부여받은 App Key 인증키를 통해 어떤 Bot에서 받은 요청인지 인증, 권한을 검사하는 작업이 필요하다.

이런 경우에 시작 가이드에는 사전에 인증키를 어떻게 발급하고, 어떤 용도로 사용되는지 상세히 설명되어야 한다.

 

• API 사용 시퀀스

API를 사용하기 위한 순서와 시퀀스가 존재할 수 있다. 이러한 시퀀스를 명시하지 않는다면 외부 개발자들은 스스로 확인하며 API를 호출하다가, API 개발자의 의도와는 맞지 않게 다른 순서로 호출을 해서 원하는 결과를 얻지 못할 수도 있다.

그러므로 API 사용 시퀀스가 존재한다면 넘버링 형식으로 시퀀스를 정리해주는 것이 좋다.

 

API 레퍼런스

API란, 특정 기술을 사용하기 위한 약속이다.

이 약속들은 보통 요청 방식, 요청 파라미터 유형, 파라미터의 필수 여부 등을 의미한다.

개발자는 이 약속들을 확인하고, 용도에 맞는 코드를 작성해야 한다.

API 별 요청과 응답을 정리해놓은 문서가 바로 API 레퍼런스이다. 대게 Request와 Response로 구성된다.

 

• 요청 Request

요청을 제대로 하기 위해서는 특정 항목들을 일정 포맷에 따라 호출해야 한다.

카카오에선 API 요청을 문서로 정리할 때 Request Syntax, Request Header, Request Element로 구분하고, 모든 서비스에 이 구성을 적용한다.

 

1. Request Syntax

API의 형태, 구조에 대한 정의를 나타낸다.

API가 어떤 메서드를 사용하고, 요청 URL의 형태는 무엇인지, 코드 예제와 함께 제공한다.

 

2. Request Header

요청에 대한 추가 정보를 담고 있는 부분.

예를 들어 메시지의 총 길이 Content-Length, 형식 Content-Type 등이 Header에 포함될 수 있다.

앞에서 발급받은 인증을 위한 정보(토큰 등)을 Header에 작성하기도 한다.

 

3. Request Element

해당 요청의 실제 메시지, 내용이 해당된다.

Request Element에는 API를 요청하기 위한 파라미터, 파라미터 유형, 필수 여부와 설명, 제약 사항 등이 제공되어야 한다.

간혹 Element가 없는 요청도 있는데, 정보를 검색, 불러오기 위한 GET 메소드의 경우 Element가 없는 요청이 나타나기도 한다.

 

• 응답 Response

응답은 API 요청에 대한 결과값을 의미한다.

예를 들어 특정 채팅방에 메시지를 전송하면, 정상적으로 전송되었는지 전송 결과를 확인할 수 있다.

 

 

1. Response Element

API 요청에 대한 결과값 확인.

요청한 API의 메서드에 따라 응답 형태는 달라질 수 있다.

POST와 같이 값을 Body에 실어 보낼 때는 해당 값이 잘 저장되었는지, 전달되었는지를 나타내는 성공 여부를 나타내기도 하고, GET과 같이 특정 정보를조회하거나 받아올 때는 값들로 코드를 확인할 수 있거나 자동적으로 다운로드 되기도 한다.

Response Element에는 필드, 필드 유형, 필수 여부와 설명이 제공되어야 한다.

 

 

좋은 API 문서 작성 팁

API 리스트업

하나의 API 레퍼런스 안에는 여러 개의 다양한 API가 제공된다.

개발자는 사실 모든 API를 사용한다기 보다는 개발하고자 하는 기능에 맞는 API를 선택해서 사용한다.

이 때, API를 종류에 따라 구분하고 한 눈에 리스트업 한 후 링크를 활용해 바로가기를 한다면, API 사용이 더욱 쉬울 것이다.

 

시각적 UI 활용

API 문서는 파라미터 설명, 예제 코드, API 설명이 반복되는 글이다.

이는 읽는 사람이 매우 지루할 수 있으므로 테이블 계층화나 코드 블럭 등 시작적인 요소를 활용해서 직관적으로 글을 작성하는 것이 필요하다.

 

• 테이블 계층화

요청, 응답에서 사용되는 파라미터는 파라미터의 이름, 필수여부, 설명을 담고 있는다.

이를 한줄씩 나열하면 줄글로 길어지기 마련이다. 이럴 땐 구분을 쉽게 하기 위해 테이블로 계층화하는 방법이 있다.

응답 파라미터 요소 중 파라미터 값 아래에 세부 파라미터들이 생기는 경우가 있는데, 이 때 계층화를 사용하면 전체적인 API의 구성을 직관적으로 확인할 수 있다.

 

• 코드블럭 활용

API 사용시, 파라미터의 이름이나 필수 작성 값, 고정값 들은 그대로 작성되어야 한다.

따라서 고정된 값들을 작성할 경우, 코드 블록을 적용해보자.

독자들은 해당 코드가 고정되어야 하는 값이라는 걸 쉽게 인식할 수 있다.

이러한 정보는 일관적으로 메시지를 전달하기 위해 모든 API에 일괄적으로 적용하는 것이 좋다.

또한 에러 코드 등, 강조가 필요한 경우에도 코드 블럭을 사용하면 좋다.

 

지속적인 업데이트

API는 기술의 변화와 사용자의 피드백을 반영해 지속적으로 업데이트 된다.

API는 업데이트 되었는데, 레퍼런스 문서가 그대로라면 해당 문서는 뒤떨어진 문서가 된다.

사용자 입장에서는 문서의 지시를 분명히 따랐음에도 불구하고, API를 원하는 대로 사용할 수 없거나 잘못된 결과를 받을 수 있다. 그러므로 지속적인 문서의 업데이트는 필수이다.

 

출처 : https://tech.kakaoenterprise.com/127