[Backend]API 정의서 만들기

 

---

📌 본 포스팅은 API 정의서에 대한 내용을 다룹니다.
📌 [카카오 엔터프라이즈 테크 문서 API 톺아보기](https://tech.kakaoenterprise.com/127)

---

1. API 정의

API(Application Programming Interface) : 서버 클라이언트 간 데이터 매개체

2. API 문서 구성

1. 간략한 소개 및 사전작업 설명

간략한 소개, 개발배경, 비즈니스 목적과 api 의 장점, 외부 독자 타겟 테크니컬 라이팅
api 사용에 앞서 보통 계정을 등록하거나 api key 등록과 인증하는등의 사전 작업이 필요하마.
Web api 사용해서 bot 생성할 뗴 자동으로 부여받은 인증키로 bot 에서 받은 요청인지 인증및 권한 검사 작업.

2. api 사용 시퀀스 (넘버링), 순서 가이드

: ex) 봇 생성 시퀀스 : 사전작업 -> 특정 멤버 조회 -> 채팅방 생성 -> 메세지 전송
만약 시퀀스가 명시되지 않으면 순서에 맞지않게 api 를 호출해서 원하는 결과가 나오지 않을 수 있음.

3. API 레퍼런스

api 별 요청-응답방식, 요청 파라미터 유형, 파라미터 필수여부를 정리해 놓은 문서

3.1 요청(Request)

특정 항목 일정 포멧에 따라 호출. Request syntax, Request header, Request element 로 구분.

• 어떤 요청 방식 인지
• 요청이 실행 되는 곳
• 요청을 하기 위한 인증방식
• 어디로 전송할 것인지
• 전송할 메세지 내용
• 글자수 제한
• 전송 형태
• 요청 테스트 가능 여부

request syntax : api 형태, 구조에 대한 정의
- 어떤 메서드 사용하는지
- 요청 url 의 형태
- 코드 예제 제공 .

코드 예제 | message.send Request syntax

curl -X POST https://api.kakaowork.com/v1/message.send\
-H "Authorization:Bearer{YOUR_APP_KEY}"\
-H "Content-Type:application/json"\
-d '{"conversation_id":"{메세지를 보낼 채팅방 ID}", "text":"Hello"}

3.2 Request Header

• 요청에 대한 추가 정보.
  ex) 메세지 총길이(Content-Length), 형식(Content-Type)등
  Request, Response 형식 ex) application/json , application/x-www.form-urlencode 등.

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

3.3 Request Element

• 해당 요청의 실제 메세지, 내용
• 파라미터와 파라미터의 유형, 필수 여부와 설명, 제약 사항 제공
• 4. 응답
• 4.1 Response Element
• api 요청에 대한 결과 값 확인 .
• 요청한 메서드에 따라 응답 형태 달라짐. POAR 와 같이 Body에 실어 보낼때 해당 값이 잘 저장 되었는지 .
  전달 되었는지 나타내는 성공여부
  GET 과 같이 특정 정보 조회하거나 받아올떄 값들을 코드로 확인하거나 자동적 다운로드
  Response element 에 필드, 필드 유형 , 필수 여부와 설명이 제공
  ex. 개발자가 고객의 메일주소 가져오려면 메일주소의 필드명을 알아야함.

4. API 리스트 업

예시

api 종류	api 명	설명
Users	users.info	특정 멤버의 상세 정보 획득
	users.find_by_mail	이메일 주소로 워크스페이스 멤버의 정보 획득
	users.find_by_phone_number	전화번호로
	users.list	워크스페이스 멤버 목록 획득
	users.set_work_time	특정 멤버 근무시간 갱신
	users.set_vacation_time	특정 멤버 휴가 시간 갱신
Conversations	conversations.open	봇과 멤버간 채팅 생성
	conversations.list	봇이 생성한 채팅방 조회
	conversations.users	봇이 생성한 채팅방 사용자 리스트 조회
	conversations.invite	봇이 생성한 채팅방에 초대
	conversations.kick	내보내기
messages	messages.send	채팅 메시지 전송
Reactive	submit_action	사용자 정보와 메세지의 정보를 고객사 서버로 전달.
	request_modal	modal 구성하는 json 받음
	submit_modal	사용자 입력 정보 고객사 서버에 최종 전달
Departments	departments.list	전체 부서 목록, 상세 정보조회
Spaces	sapces.info	워크스페이스 정보조히
Bots	bots.info	봇 정보 조회

6. 시각적 ui 활용

• 테이블 계층화, 코드블럭 등 시각적 요소 활용하여 직관적 글작성
  파라미터(파라미터 이름, 타입, 필수여부, 설명 ) 글보다 테이블화해서 설명
• 코드 블럭 활용
• 지속적인 업데이트 필요