캘린더 API 개요
NAVER WORKS 캘린더 API(이하 '캘린더 API' 또는 'API')는 HTTP 요청으로 활용할 수 있는 REST API로 API 결과는 JSON 형식으로 반환된다. 인증 방식으로는 OAuth 2.0을 사용한다.
캘린더 API는 NAVER WORKS 캘린더 서비스의 기능 중에서 자주 사용하는 기능을 API로 제공한다.
API 공통 정보
제공 환경
NAVER WORKS에서는 테스트와 서비스의 2가지 환경을 제공한다. 그러나 캘린더에서는 서비스 환경만 제공한다.
- 서비스 환경: https://apis.worksmobile.com
오퍼레이션을 요청할 때는 HTTP 메서드와 요청 URL을 결합한다. 예를 들어, 서비스 환경에서 캘린더를 생성하는 오퍼레이션은 다음과 같다.
예) 캘린더 생성 오퍼레이션
- POST https://apis.worksmobile.com/{API ID}/calendar/createCalendar
개별 API 설명에서 서비스 환경에 대한 요청 URL을 확인할 수 있다.
Request 공통
NAVER WORKS 액세스 토큰과 컨슈머키
API를 호출할 때는 반드시 헤더에 NAVER WORKS 액세스 토큰과 컨슈머키를 포함해야 한다. NAVER WORKS 액세스 토큰은 로그인할 때 발급받을 수 있고, 매번 로그인할 때마다 재발급된다.
컨슈머키 발급은 API 공통가이드 을 참고한다.
헤더에 NAVER WORKS 액세스 토큰과 컨슈머키를 설정하는 방법은 다음과 같다.
httpMethod.setRequestHeader("Authorization", "NAVER WORKS 액세스 토큰");
httpMethod.setRequestHeader("consumerKey", "컨슈머키");
userId
API Gateway(APIGW)를 사용하는 클라이언트는 쿠키를 기반으로 인증한다. 이때 APIGW에서 쿠키를 파싱해서 캘린더 API를 호출할 때 userId 파라미터를 추가해서 호출하므로, 클라이언트에서는 별도의 userId 파라미터 값을 입력할 필요가 없다.
참고
- API 인증과 관련된 자세한 내용은 API 인증 준비를 참고한다.
Response 공통
API 호출에 실패하면 오류 내용이 반환된다.
속성 | 타입 | 필수 여부 | 설명 |
---|---|---|---|
result | String | Y | 호출 실패 시 고정값 "fail" 반환. |
errorMessage | String | Y | |
serverName | String | Y | API가 호출된 캘린더 서버 |
calledTimestamp | String | Y | 호출된 시간 |
requestUri | String | Y | 호출된 API URI |
remoteIp | String | Y | 캘린더 서버를 호출한 IP |
result | String | Y | 원인 추적을 위한 메시지 |
예를 들면 다음과 같다.
{
"result": "fail",
"errorMessage": "{\"serverName\":\"cvcapi02.caldf\",
\"calledTimestamp\":\"2016-08-25T14:58:24.760+09:00\",
\"requestUri\":\"/apigw/deskhomeBO/getScheduleList\",
\"remoteIp\":\"10.64.54.204\",
\"result\":\"com.naver.calendar.apigw.post.bean.CalendarException: cannot find userConf. userId\\u003d33578002\"
}"
}