API 호출

    오퍼레이션을 요청할 때는 HTTP 메서드와 요청 URL을 결합한다. 예를 들어, 메일을 발송하는 오퍼레이션은 다음과 같다.

    예) 메일 발송 오퍼레이션

    • POST https://apis.worksmobile.com/{API ID}/mail/sendMail

    개별 API 설명에서 서비스 환경에 대한 요청 URL을 확인할 수 있다.

    Request 공통

    API를 호출할 때는 반드시 헤더에 NAVER WORKS 토큰과 컨슈머키를 포함해야 한다. NAVER WORKS 토큰 및 컨슈머키 발급 방법은 API 인증 준비를 참고한다.

    헤더에 NAVER WORKS 토큰과 컨슈머키를 설정하는 방법은 다음과 같다.

    주의

    • Authorization 타입으로 'Bearer'를 반드시 명시해야 하며, 'Bearer'와 'Token' 사이에 공백(space)을 빠트리지 않도록 주의한다.
    method.setRequestHeader("consumerKey", "컨슈머키");
    method.setRequestHeader("Authorization", "Bearer 토큰");
    

    Response 공통

    API 호출에 실패하면 오류 코드와 오류 메시지가 반환된다.

    참고

    • API 성공 시 결과 형태는 API마다 다르므로 개별 API 설명을 참고한다.
    속성 타입 필수 여부 설명
    errorCode String Y 오류 코드
    errorMessage String Y 오류 메시지

    상세한 오류 코드와 오류 메시지 종류는 다음과 같다.

    코드 REST HTTP 상태 코드 메시지 설명
    001 404 Not support url 지원하지 않는 URL로 호출
    002 404 Not support port 지원하지 않는 Port로 호출
    024 401 Authentication failed 컨슈머키와 토큰의 인증 실패
    028 401 Authentication header not exists 컨슈머키와 토큰이 헤더에 없음
    029 401 Malformed authentication header 헤더의 컨슈머키와 토큰 형식이 틀림
    041 403 Not allowed tenantApiId 허가되지 않은 고객사 API ID로 호출
    042 403 Not allowed consumerKey 허가되지 않은 컨슈머키 호출
    043 403 Not allowed remote ip 허가되지 않은 IP에서 호출
    044 403 Not allowed domainId 허가되지 않은 도메인 호출
    045 403 Not allowed service 권한이 없는 서비스 호출
    051 404 Api not exists 존재하지 않는 API
    064 405 Malformed http method 지원하지 않는 HTTP Method
    065 400 Mandatory parameter not exists 필수 파라미터 없음
    081 400 Target not exists 대상이 존재하지 않음
    083 500 Additional information fail 추가 정보 획득에 실패
    085 429 Daily quota fail 일별 쿼터 초과
    086 503 Service use fail 서비스(메일, 메시지 봇 등) 사용 실패
    087 403 Domain stop 도메인이 일시 정지된 경우
    088 403 Blacklist 도메인 또는 IP 주소가 blacklist인 경우
    089 400 Malformed json parameter contentType이 application/json인데 파라미터가 JSON 형식이 아닌 경우
    090 503 Service fail 서비스(메일, 메시지 봇 등) 내부 오류
    예) {errorMessage=Service fail, HTTP/1.1 400 bad_path(name), errorCode=090}
    092 429 API rate limit exceeded Rate Limit 초과
    999 500 Unknown error 알 수 없는 에러

    API별로 발생하는 오류 코드와 오류 메시지는 각 API 설명에서 확인할 수 있다.

    샘플 코드

    서비스 API 샘플 코드

    소스 코드에 필요한 consumerKey는 Developer Console에서 발급받는다.

    
    /* authorization code 요청 */
    
    var consumerKey = "LQwDde6x8eV4ROOCOdSW";
    var url = "https://auth.worksmobile.com/oauth/authorize?client_id=" + consumerKey
                   + "&redirect_uri=https://mydomain.com/getToken"
                   + "&domain=mydomain.com";
    
    window.open(url, 'authorize' , 'width=600px,height=800px');
    
    
    /**
     * https://mydomain.com/getToken
     * Authorization Code 획득 후 Access Token 요청
     */
    
    import org.apache.commons.httpclient.HttpClient;
    import org.apache.commons.httpclient.NameValuePair;
    import org.apache.commons.httpclient.methods.PostMethod;
    
    public class ServiceApiTest {
    
        public void testGetAccessToken() throws Exception {
            String url = "https://auth.worksmobile.com/oauth/token";
            String consumerKey = "LQwDde6x8eV4ROOCOdSW";
            String authorizationCode = "QkJxMFc4ekRnMGdLNjhOMQ==";
            String domain = "mydomain.com";
    
            PostMethod method = new PostMethod(url);
            NameValuePair[] parameters = new NameValuePair[3];
            parameters[0] = new NameValuePair("client_id", consumerKey);
            parameters[1] = new NameValuePair("code", authorizationCode);
            parameters[2] = new NameValuePair("domain ", domain);
            method.setRequestBody(parameters);
    
            HttpClient client = new HttpClient();
            client.executeMethod(method);
            String response = method.getResponseBodyAsString();
    
            System.out.println("response=" + response);
            /* response={"errorCode":"00","expire_in":"604800","refresh_token":"AAAAT/bdZsj81ULzym+URwKwM+OEj69MPhkqDuFiWMRjSZkR+Yk","access_token":"AAAA67h9/36ItvAEea7G8ijrDeCy/22BO5IcP0/KkwZO6unIYET6xkmp3RLW"}
             response에서 accessToken을 추출하여 별도 저장할 것을 권장 */
        }
    }
    
    
    /** 
     * 서비스 API 호출
     */
    
    import org.apache.commons.httpclient.HttpClient;
    import org.apache.commons.httpclient.NameValuePair;
    import org.apache.commons.httpclient.methods.PostMethod;
    
    public class ServiceApiTest {
    
        public void testServiceApi() throws Exception {
            String url = 
                 "https://apis.worksmobile.com/kr1wwTrYrbIot/calendar/getCalendar";
            String consumerKey = "LQwDde6x8eV4ROOCOdSW";
            String token = "AAAA67h9/36ItvAEea7G8ijrDeCy/22BO5IcP0/KkwZO6unIYET6xkmp3RLW";
    
            PostMethod method = new PostMethod(url);
            method.setRequestHeader("consumerKey", consumerKey);
            method.setRequestHeader("Authorization", "Bearer " + token);
    
            NameValuePair[] parameters = new NameValuePair[1];
            parameters[0] = new NameValuePair("calendarId", "1234");
            method.setRequestBody(parameters);
    
            HttpClient client = new HttpClient();
            client.executeMethod(method);
            String response = method.getResponseBodyAsString();
    
            System.out.println("response=" + response);
        }
    }
    

    서버 API 샘플 코드

    소스 코드에 필요한 consumerKey와 token은 Developer Console에서 발급 받는다.

    
    /** 
     * 서버 API 호출
     */
    
    import org.apache.commons.httpclient.HttpClient;
    import org.apache.commons.httpclient.NameValuePair;
    import org.apache.commons.httpclient.methods.PostMethod;
    
    public class ServerApiTest {
    
        public void testServerApi() throws Exception {
            String url = 
                         "https://apis.worksmobile.com/kr1wwTrYrbIot/admin/getDomain";
            String consumerKey = "dz0jtXyXc9Zo953HdjZA";
            String token = "AAAA67h9/36ItvAEea7G8ijrDeCy/22BO5IcP0/KkwZO6unIYET6xkmp3RLWt";
    
            PostMethod method = new PostMethod(url);
            method.setRequestHeader("consumerKey", consumerKey);
            method.setRequestHeader("Authorization", "Bearer " + token);
    
            NameValuePair[] parameters = new NameValuePair[1];
            parameters[0] = new NameValuePair("params", "{\"domain\":\"mydomain.com\"}");
            method.setRequestBody(parameters);
    
            HttpClient client = new HttpClient();
            client.executeMethod(method);
            String response = method.getResponseBodyAsString();
    
            System.out.println("response=" + response);
        }
    }
    

    동시 접속

    동시 접속 가능 요청 수는 5이다. 허용된 동시 접속 요청 수를 넘으면 API 호출에 실패할 수 있다.

    Rate Limit

    Rate Limit란 특정 시간 내에 할 수 있는 API 호출 수를 의미한다. 사용자의 API 호출 수가 Rate Limit값을 초과하면 API 호출이 제한되며 요청이 실패하게 된다. 실패 시엔 아래와 같은 응답을 반환한다.

    코드 REST HTTP 상태 코드 메시지 설명
    092 429 API rate limit exceeded Rate Limit 초과

    Message, Contact, Organization 3개의 서비스에 Rate Limit가 적용되며, Rate Limit값은 상품별로 차등 적용한다.

    적용대상

    Category Product Rate Limit
    Message Free 1 API 당 60/min
    Message Lite, Basic, Premium 1 API 당 200/min
    Contact Lite, Basic, Premium 1 API 당 120/min
    Organization Lite, Basic, Premium 1 API 당 1000/min
    아래의 API들은 1 API당 600 request/min으로 변경
    ● 구성원 추가
    ● 구성원 수정
    ● 구성원 부분 수정
    ● 구성원 삭제
    ● 구성원 삭제 취소
    ● 구성원 즉시 삭제

    참고

    • Organization API 사용 시 주의를 확인한다.

    Rate Limit가 적용된 Message, Contact, Organization API를 호출하면 아래와 같이 응답에 3가지 헤더가 추가된다. 이를 통해 현재 API 호출 수, 남은 API 호출 수, 갱신까지 남은 시간을 알 수 있다.

    헤더 설명 단위
    RateLimit-Limit 기준 시간 단위 API 호출 수
    RateLimit-Remaining 기준 시간 단위 남은 API 호출 수
    RateLimit-Reset 기준 시간 갱신까지 남은 시간