API 1.0 개요
NAVER WORKS에서 제공하는 API의 종류와 인증 방식을 설명한다.
동영상 가이드
API 종류
NAVER WORKS Bot Platform API는 서비스 API와 서버 API 두 가지 종류로 나뉜다. 자세한 내용은 각 API 명세에서 기술한다. 종류가 명시되지 않은 API는 서비스 API이다.
서비스 API
사용자가 로그인한 후 사용할 수 있는 API로, 본인의 데이터에만 접근할 수 있다. 단, 캘린더의 "다른 사람의 일정 목록 조회" API처럼, 도메인 내 다른 사용자의 데이터에 접근 가능한 API도 일부 존재한다.
서버 API
사용자의 로그인 없이 사용할 수 있는 API로, 도메인 내 모든 사용자의 데이터에 접근할 수 있다. 대표적으로 조직 연동과 마이그레이션 API가 서버 API이다.
API 인증
서비스 API와 서버 API는 모두 OAuth 2.0을 기반으로 하지만, 인증 방식은 서로 다르다.
서비스 API 인증 방식
서비스 API의 인증 방식은 다음과 같다.
- 서비스 API 사용에 필요한 정보를 발급받는다. 사용자는 NAVER WORKS Developer Console에서 서비스 API 사용에 필요한 정보를 발급받는다. 자세한 내용은 API 인증 준비 를 참고한다.
- 서비스 API에 필요한 정보를 제공한다.
- Authorization code 발급을 요청한다(window open). 새 창으로 Authorization code 발급 요청을 한다. 이때 NAVER WORKS Developer Console에서 발급받은 서비스 API 컨슈머키를 사용한다.
- NAVER WORKS 로그인 창을 제공한다. NAVER WORKS에 로그인되어 있지 않으면, 로그인 창을 제공한다. 이미 로그인이 되어 있으면 이 과정은 생략된다.
- ID/Password를 입력한다. NAVER WORKS 로그인 창에서 ID/Password를 입력하여 로그인한다.
- 인증 확인 후 Authorization code를 발급한다. ID/Password를 검증한 후, Authorization code를 발급하여 3번 요청 시 전달된 redirect_uri 파라미터로 전달한다.
- Access Token을 요청한다(API call). Authorization code를 이용하여 Access Token을 요청한다. Authorization code는 일회성이다.
- Access Token을 발급한다. Authorization code를 검증한 후, Access Token을 발급한다.
- 필요한 정보를 Header에 추가하여 API를 호출한다. 서비스 API 호출 시 컨슈머키와 Access Token을 Header에 추가하여 호출한다.
- Header 정보의 유효성을 확인하고, API를 처리한다. NAVER WORKS은 Header 정보의 유효성을 확인하고, API를 실제로 처리한다.
- API 처리 결과를 반환한다.
참고
- API를 호출할 때마다 Access Token을 발급받을 필요는 없다(3~8번 과정).
- 한 번 발급받은 Access Token은 별도로 저장해 놓고 재사용할 수 있다(예: 쿠키).
서버 API 인증 방식
서버 API 인증 방식은 다음과 같다.
그림 2 서버 API 인증 방식
- 서버 API 사용에 필요한 정보를 발급받는다. 사용자는 NAVER WORKS Developer Console에서 서버 API 사용을 위해 필요한 정보를 발급받는다. 자세한 내용은 API 인증 준비 를 참고한다
- 서버 API 사용에 필요한 정보를 제공한다.
- 필요한 정보를 Header에 추가하여 API를 호출한다. 서버 API 호출 시 컨슈머키와 Server Token을 Header에 추가하여 호출한다.
- Header 정보의 유효성을 확인하고 요청 IP를 확인한 후, API를 처리한다. NAVER WORKS는 Header 정보의 유효성을 확인하고, Developer Console에서 Token 발급 시 등록한 서버 IP와 실제 API를 요청한 클라이언트 IP가 동일한지 확인한 후, API를 처리한다.
- API 처리 결과를 반환한다.