이 문서는 API 제공자를 위한 카카오 API 플랫폼 연동 방법에 대해 안내합니다.

API 제공자가 카카오 API 플랫폼과 연동하기 위해 해야 할 일을 단계별로 안내합니다.

API 제공자가 API플랫폼에 API 연동을 위한 협의를 요청하는 단계입니다. API 연동에 필요한 정보를 [서비스] API플랫폼 아지트로 전달 후 관련 세부 사항을 상호 협의해야 합니다.

협의 내용을 반영해 API 제공자가 연동 설정과 개발을 수행합니다. 개발 중 변경 또는 문의 사항은 [서비스] API플랫폼 아지트로 전달합니다.

연동을 마무리하고 API를 오픈하는 단계입니다. API 오픈 전, 아래 항목의 필요 여부를 점검하고 준비해야 합니다.

• 문서: [문서] 영역에서 제공하는 API 개발 문서
• 개발 도구: [도구] 영역에서 제공하는 API 관련 기능
• API 안내와 홍보: 아래 수단 사용 가능
  • 이메일: 카카오디벨로퍼스 개발자 대상
  • 공지: 데브톡(개발자 포럼)
• 운영 준비
  • 제휴 필요 API를 제공하는 경우 제휴 방안
  • 개발자 포럼에서의 문의와 CS의 대응 방안
  • API 운영 시 참고 사항 참고

API 플랫폼 연동 방안 협의 시, 전달해야 하는 정보에 대해 안내합니다.

• 담당자 및 담당 부서 멘션 정보(예: @@api)
• API 제공자의 카카오디벨로퍼스 앱 ID
• 연동 대상 API 정보
  • 기능 및 소개
  • 희망 연동 방식: KAPI 패시브 연동 방식인 경우 패시브 연동 API 정보 전달 내용 포함 필요
  • 제공 범위: 제휴 API인 경우 제휴 방식에 대한 내용 포함 필요
  • 지원 페이즈(Phase): 페이즈별 API 정보 포함 필요
  • 권한과 쿼터의 적용 여부, 적용 시 세부 내용 전달 필요
• 상태 확인 API 제공 여부: KAPI 패시브 연동 방식의 경우 필수
• 플랫폼 제공 기능에 대한 API 제공자의 요구 사항
• 아래에 해당하는 경우, 관련 아지트에 문의 후 검토 의견 포함 필요
  • 개인정보 또는 법적 문제 발생 가능성이 있는 경우: [법무팀] 법률자문 아지트로 문의
  • API 제공자가 공동체인 경우: 카카오와 해당 공동체간 API 제공 계약 필요, 카카오 기술기획팀 아지트로 문의

• 각 API는 원하는 인증 방식, 권한, 쿼터를 별도로 설정할 수 있습니다.
• 아래의 경우 임의의 경로(Path) 하나만 등록해 사용할 수도 있습니다.
  • REST API: API별 인증 방식, 권한, 쿼터, 통계 정보를 구별할 필요가 없는 경우
  • SDK: 사용자가 제공자 API를 호출하지 않는 경우

아래 선택지를 참고해 카카오 API 플랫폼과 연동할 API에 적합한 연동 방식을 선택합니다. 관련 문서에서 자세한 내용을 확인할 수 있습니다.

• KAPI 액티브(Active) 연동: 카카오 API 플랫폼이 API 요청을 받고, API 제공자의 PAPI를 활용해 응답 반환
  • 권장 대상: 사용자의 카카오 로그인 필요, 기존 카카오 API와 연계 기능 존재, 입출력 데이터 정제 필요
• KAPI 패시브(Passive) 연동: API 제공자가 API 요청을 받고, 카카오 API 플랫폼의 인증과 쿼터 시스템을 활용해 응답 반환
  • 권장 대상: 사용자의 카카오 로그인 필요, 데이터의 입출력이 잦거나 큼, API Front 서버 운영이 어려움
• 기타 연동 방식
  • KAPI 게이트웨이(Gateway): 카카오 API 플랫폼이 API 요청을 받고 API 제공자의 PAPI 서버로 바이패스(Bypass)
  • DAPI: 게이트웨이 플랫폼인 APIHub에 API 제공자가 직접 API를 등록하고 관리

KAPI 액티브(Active) 연동은 카카오 API 플랫폼이 API 요청(Request)을 받고 응답(Response)을 반환하는 연동 방식입니다. 요청 처리 시 API 제공자의 PAPI를 사용합니다. 호스트는 kapi.kakao.com입니다.

일관된 포맷(Format)과 UI/UX로 편의를 제공하고, 다른 KAPI와의 시너지를 유도할 수 있습니다. KAPI는 페이즈(Phase)별 API를 제공하므로, PAPI 또한 알파(Alpha), 샌드박스(Sandbox), 베타(Beta), 프로덕션(Production) 페이즈별로 API를 제공해야 합니다.

아래는 KAPI 액티브 연동 API 요청의 처리 과정입니다.

1. API 사용자가 KAPI의 엔드포인트(Endpoint)로 API 요청을 보냅니다.
2. 카카오 API 플랫폼이 요청에 대한 인증, 권한, 쿼터를 확인해 유효성을 검증합니다.
3. 카카오 API 플랫폼이 API 제공자의 PAPI를 호출합니다.
4. 카카오 API 플랫폼이 PAPI 응답을 받아 공통 응답 포맷에 맞게 정제합니다.
5. 카카오 API 플랫폼이 API 사용자에 응답을 반환합니다.

KAPI 패시브(Passive) 연동은 API 제공자가 API 요청을 받고 응답을 반환합니다. 요청의 처리 과정에서 카카오 API 플랫폼의 인증과 쿼터 시스템을 활용합니다. 호스트는 API 제공자가 지정합니다.

API 요청 및 응답 규격 변경, SDK 제공 등 변경 사항에 유연하게 대처할 수 있습니다. 또한 데이터 용량이 크거나 처리(Processing) 비용이 비싼 경우에도 다른 연동 방식 대비 효율적입니다. API 제공자가 입출력 데이터를 정제해야 하고, 프론트(Front)를 운영하는 비용이 발생합니다.

아래는 KAPI 패시브 연동 API 요청의 처리 과정입니다.

1. API 사용자가 API 제공자의 엔드포인트(Endpoint)로 API 요청을 보냅니다.
2. API 제공자는 패시브 연동 API를 호출해 API 사용자의 정보와 권한, 쿼터를 확인합니다.
3. API 제공자는 패시브 연동 API 요청 결과에 따라 API 요청을 처리합니다.
4. API 제공자가 API 사용자에게 응답을 반환합니다.

KAPI 패시브 연동 방식의 API는 카카오모먼트 API가 있습니다.

KAPI 게이트웨이(Gateway) 방식은 카카오 API 플랫폼이 요청을 받아 API 제공자의 PAPI 서버로 바이패스(Bypass)합니다. 카카오 API 플랫폼은 요청의 유효성 검증(인증, 권한, 쿼터 확인)만 수행합니다. PAPI 서버에서 실제 요청을 처리하고 전달한 결과를, 카카오 API 플랫폼이 사용자에게 응답합니다.

일관된 포맷의 API를 제공할 수 있도록 응답에 대한 에러 코드 매핑(Mapping), 에러 래핑(Wrapping) 기능을 제공합니다. 입출력 데이터는 API 제공자가 정제해야 합니다. 일반적으로 KAPI 게이트웨이 방식보다는 다양한 상황에 적합하고 장점이 많은 KAPI 패시브 연동을 사용하는 편을 권장합니다.

카카오 API 플랫폼이 제공하는 게이트웨이 플랫폼인 APIHub에 API 제공자가 직접 API를 등록하고 관리합니다. APIHub이 제공하는 기능은 APIHub 문서를 참고합니다.

DAPI 방식의 API 중 Daum 검색, 지도, 로컬 API의 호스트는 dapi.kakao.com입니다. 이외의 API의 호스트는 https://apihub-gateway.kakao.com이며, APIHub 마켓플레이스에서 전체 목록을 확인할 수 있습니다.

카카오 API 플랫폼은 아래 인증 수단을 제공합니다. 인증엔 API 호출 시 헤더에 포함한 인증 정보를 사용합니다.

• 카카오디벨로퍼스 앱 인증: 앱 관리 페이지의 [앱] > [플랫폼 키]와 [앱] > [어드민 키]에서 조회한 플랫폼 키와 어드민 키
• 사용자 인증: 카카오 로그인으로 발급된 토큰
• 추가 인증
  • iOS SDK: 앱 관리 페이지의 [앱] > [제품 링크 관리] > [네이티브 앱 스킴]에 등록된 번들 ID(Bundle ID)
  • Android SDK: 앱 관리 페이지의 [앱] > [제품 링크 관리] > [네이티브 앱 스킴]에 등록된 키 해시(Key hash)
  • JavaScript SDK: 앱 관리 페이지의 [앱] > [플랫폼 키] > [JavaScript 키]에 등록된 JavaScript SDK 도메인
  • IP 주소: 앱 관리 페이지의 [앱] > [플랫폼 키] > [REST API 키] 또는 [앱] > [어드민 키]에 등록된 호출 허용 IP 주소

각 API의 권한을 설정할 수 있습니다. API 플랫폼은 권한이 설정된 API 요청을 받으면 사용자의 권한 보유 여부를 확인합니다. API 제공자는 원하는 방법으로 권한 부여와 회수를 포함한 관리를 할 수 있습니다.

카카오 API 플랫폼에서 제공 중인 API의 권한 정보는 권한에서 확인할 수 있습니다.

카카오 API 플랫폼은 API 사용량을 제한하는 쿼터 시스템을 제공합니다. 쿼터는 앱 기준으로 적용하며 일, 월별 쿼터와 초당 burst 제한을 적용할 수 있습니다. 또한, API별 사용량, 파라미터 길이, 파일 크기, 프레임 수와 같은 데이터 쿼터도 적용할 수 있습니다. 사용자에게 고지하는 오픈 API의 쿼터 정보는 쿼터에서 확인할 수 있습니다.

앱 관리 페이지의 [통계] 메뉴에서 각 앱의 API 사용 통계를 제공합니다. 또한 카카오 API 플랫폼 시스템 분석 도구인 Capri Cave로 다양한 정보를 제공합니다. 자세한 정보는 통계를 참고합니다.

카카오 API 플랫폼의 SDK(Kakao SDK)에 연동 대상 API를 함께 제공해, 네이티브(Native)나 웹 환경에서 간편하게 사용하도록 지원할 수 있습니다. 아래 플랫폼별 SDK 문서를 참고합니다.

• JavaScript SDK
  • 시작하기, 다운로드, 레퍼런스, 데모
• Android SDK
  • 시작하기, 다운로드, 레퍼런스
• iOS SDK
  • 시작하기, 다운로드, 레퍼런스, Rx 레퍼런스
• Android Partner SDK
  • 시작하기, 다운로드, 레퍼런스
• iOS Partner SDK
  • 시작하기, 다운로드, 레퍼런스, Rx 레퍼런스

카카오디벨로퍼스의 [도구] 메뉴에서 사용자들이 API를 테스트하는 기능을 제공할 수 있습니다.

• REST API 테스트

개발자 포럼인 데브톡(Dev Talk)에서 API 사용자의 문의에 답변하거나 제보를 받을 수 있습니다.

카카오디벨로퍼스의 [문서] 메뉴에서 API 사용자를 위한 개념, 설정, 개발 내용을 안내하는 문서를 제공할 수 있습니다.

연동 대상 API가 오픈 API인 경우 카카오 오픈 API 상태 확인 페이지로 API 상태 정보를 제공할 수 있습니다. 자세한 안내는 카카오 오픈 API 상태를 참고합니다.

API 제공자가 API 운영 시 참고할 수 있는 관련 사이트와 문서입니다.

• 사용처 정보 확인: Capri Cave, Stat
• API 제공자의 담당자 정보 확인: 통합 API 어드민, Capri Cave
• API 사용 통계 확인과 모니터링: 통계, Capri Cave
• 사용자 피드백 청취와 기술 지원: 데브톡(개발자 포럼)

사용자의 앱 연결 상태에 따른 호출 제한, SDK 지원 여부, 권한 요구 사항은 지원 범위를 참고합니다.