API 호출

NAVER WORKS API 호출 시 알아야 할 공통 규격을 설명한다.

모든 API는 REST 형식으로 HTTPS를 통해 API 엔드포인트에 연결한다.

Authorization {#authorization}

API를 호출하려면 Access Token이 필요하다. API 호출 시 Authorization 헤더에 Bearer와 함께 Access Token을 지정해야 한다.

Authorization: Bearer {Access Token}

주의

• Bearer를 반드시 명시해야 하며, Bearer와 Access Token 사이에 공백( )을 빠뜨리지 않도록 주의한다.

Access Token은 두 가지의 방법으로 발급받을 수 있다. 자세한 내용은 인증을 참고한다.

API Endpoint {#api-endpoint}

NAVER WORKS API를 호출할 때 액세스하는 엔드포인트(URL)는 다음과 같다.

https://www.worksapis.com/v1.0/...

예) GET 메서드로 Bot 목록 조회

GET https://www.worksapis.com/v1.0/bots

HTTP Method {#http-method}

모든 API 호출은 HTTP 메서드와 URL의 조합으로 이루어진다.
HTTP 메서드는 리소스에 접근한 후의 동작을 나타내는 것으로, NAVER WORKS API에서는 다음의 HTTP 메서드를 사용한다.

• GET: 리소스 조회
  • 데이터를 검색하거나 파일을 다운로드하는 API에 사용된다.
• POST: 리소스 생성
  • 데이터 등록, Bot 메시지 전송, 파일 업로드 등 데이터 전송 API에 사용된다.
  • 요청 내용은 request body에 지정한다.
  • POST 요청으로 객체를 생성하면 일반적으로 생성된 객체가 응답으로 반환된다.
• PUT: 리소스 수정
  • 데이터를 수정하는 API에 사용된다.
  • 일반적으로 수정된 객체가 응답으로 반환된다.
  • 리소스는 request body에 지정된 값으로 변경된다.

  • 주의
    • 지정하지 않은 속성은 기본값으로 대체되거나 null 값을 지정한 것으로 처리되어 값이 손실된다.

• PATCH: 리소스 부분 수정
  • 데이터의 일부를 업데이트하는 API에 사용된다.
  • 일반적으로 수정된 객체가 응답으로 반환된다.
  • request body에서 지정한 속성만 수정하고 지정하지 않은 속성의 값은 유지된다.
• DELETE: 리소스 삭제
  • 데이터를 삭제하는 API에 사용된다.

Parameter {#request-parameter}

동일한 API에서도 지정하는 파라미터에 따라 동작이 다르다. API를 호출할 때 지정할 수 있는 파라미터는 리소스를 지정하는 'path parameter', 다른 API의 동작을 제어하는 'query parameter', 주로 객체의 속성을 지정하는 데 사용되는 'request body' 등이 있다.

주의

• path parameter와 query parameter는 URL 인코딩해야 한다.
• 반드시 문서에 정의된 파라미터를 사용한다. 그렇지 않으면 오류나 의도하지 않은 동작이 발생할 수 있다.

Path Parameter {#path-parameter}

특정 리소스를 다루는 API 호출 시 API 요청 URL의 path parameter에 대상 리소스를 식별하는 파라미터를 포함한다. path parameter는 반드시 지정해야 한다.
API 문서에서는 {parameter}로 설명한다.
예) 특정 사용자가 액세스할 수 있는 캘린더 목록 조회 API

GET /v1.0/users/{userId}

이때 {userId}는 다음 값 중 하나를 지정한다.

• 사용자 ID(userId)
  • 예: userf7da-f82c-4284-13e7-030f3b4c756x
• 이메일(email)
  • 예: user@domain
• 외부 키(externalKey)
  • 예: externalKey:ExternalKeyValue

참고

• API 문서에서는 외부 키를 externalKey:{userExternalKey} 형식으로 입력하도록 설명한다.
• {userExternalKey}를 실제 외부 키(ExternalKeyValue)로 옮긴 후 externalKey:ExternalKeyValue로 지정한다.

사용자 ID를 지정하는 API 요청 URL은 다음과 같다.

GET /v1.0/users/userf7da-f82c-4284-13e7-030f3b4c756x

API별로 지정 가능한 값은 각 API 문서를 참고한다.

me 키워드 {#me-keyword}

일부 API는 path parameter의 userId 대신 me 키워드를 사용할 수 있다. me 키워드를 사용하면 인증된 사용자의 Access Token을 사용하여 API를 호출한다.
예) 로그인한 사용자의 userId를 사용하는 경우 아래의 두 API는 동일한 결과를 반환한다.

• GET /v1.0/users/me/calendar
• GET /v1.0/users/{userId}/calendar

주의

• 서비스 계정을 사용하여 JWT 인증을 한 토큰에서는 me 키워드를 사용할 수 없다.

Query Parameter {#query-parameter}

query parameter는 호출한 API의 동작을 지정하는 데 사용된다. query parmeter에는 필수 입력값과 필수가 아닌 입력값이 있다. 자세한 내용은 각 API 문서를 참고한다.

• query parameter의 예로 목록 조회 시 조회 개수(count)와 페이징을 위한 커서(cursor) 등이 있다.
• query parameter는 요청 URL에 '?'를 추가하고 매개 변수의 이름과 값을 '='로 연결하여 지정한다. query parameter를 여러 개 지정하려면 &로 연결한다.

예) 도메인(domainId)과 조회 개수(count)를 지정해 구성원 목록을 조회하는 API

GET /v1.0/users?domainId=10000001&count=20

Request Body/Response Body {#request-response-body}

POST, PUT, PATCH 메서드의 요청 정보와 응답 형식은 JSON(JavaScript Object Notation)을 사용하며, 문자 코드는 UTF-8이다. 헤더에 다음의 Content-Type을 지정한다.

Content-Type: application/json; charset=UTF-8

참고

• 일부 API는 JSON 형식을 사용하지 않는다. 자세한 내용은 각 API 문서를 참고한다.

JSON 형식 {#json-format}

JSON에 대한 개요를 설명한다.

JSON 형식은 객체를 {와 }로 묶고 그 안에 속성 이름과 값을 쓴다. 속성 이름은 "로 감싸고 :으로 값과 연결한다. 각 속성과 객체는 ,로 구분한다.

문자열 {#json-string}

문자열(string)은 "로 묶는다.

{   "string" : "문자열"}

숫자 {#json-number}

숫자(number)는 그대로 기술한다.

{     "number" : 12345}

부울/널 {#json-bool-and-null}

부울(boolean)값과 널(null)은 모두 "로 감싸지 않고 소문자 ture, false, null로 쓴다.

{   "bool-true" : true,   "bool-false" : false,   "null" : null}

중첩 {#json-nest}

객체를 중첩(nest)하는 경우 {와 }로 감싼다.

{   "object" : {     "property1" : "value1",     "property2" : "value2"   }}

배열 {#json-array}

[와 ] 안에 여러 개의 객체 또는 값을 포함해 배열(array)로 지정할 수 있다.

{   "ObjectArray" : [     {       "object" : "1st object"     },     {       "object" : "2nd object"     }   ],   "ValueArray" : [     "ValueA",     "ValueB"   ]}

JSON에서 속성이나 객체의 순서는 의미가 없다. 또, 스페이스나 탭, 개행도 의미가 없다. 따라서 다음 두 가지는 같은 의미이다.

{   "Property1" : 1,   "Property2" : 2}

{"Property2":2,"Property1":1}

HTTP Status Code {#status-code}

API 요청 결과는 응답에 포함된 HTTP 상태 코드로 결정된다.

API 호출이 성공하면 성공을 나타내는 2xx 또는 리디렉트를 나타내는 3xx가 반환된다.
반면, API 호출이 실패하면 일반적으로 클라이언트의 요청 오류를 나타내는 4xx 혹은 서버 오류를 나타내는 5xx가 반환된다.

API 호출 시 반환되는 주요 HTTP 상태 코드는 다음과 같다.

Error Code {#error-response}

오류가 발생하면 응답 본문에 포함된 오류 코드로 내용을 확인한다.

자세한 내용은 Error Code를 참고한다.

Pagination {#pagination}

페이지 매김(pagination)은 목록 조회 API를 호출할 때 응답 결과를 여러 페이지로 구성하는 방법이다.

자세한 내용은 Pagination을 참고한다.

파일 업로드/다운로드 {#file-upload-download}

NAVER WORKS API에는 파일 데이터를 업로드하거나 다운로드하는 API가 있다. 각 API의 업로드/다운로드 방식은 동일하다.

자세한 내용은 파일 업로드/다운로드를 참고한다.

Rate Limits {#call-limitation}

서비스 안정화를 위해 API 호출 시 '호출 제한'과 '동시 접속 제한'이 적용된다. 제한값을 초과하면 일시적으로 호출이 실패한다.

자세한 내용은 Rate Limits를 참고한다.

감사 로그 {#check-api-call}

API 호출은 각 서비스의 감사 로그에 기록된다. 자세한 내용은 Admin 사용 가이드의 감사를 참고한다.

부록 {#appendix}

기타 정보는 부록을 참고한다.