Notification Hub API v1.0 공통 정보
Notification > Notification Hub > API v1.0 사용 가이드 > 공통 정보
주의 사항
- Notification Hub v1.0 API는 현재 알파(alpha) 상태로, 안정화되지 않았으며, 실험적인 기능이 추가되거나 제거될 수 있습니다.
- API는 언제든지 변경될 수 있으며, 변경 시 사전 공지 없이 변경될 수 있습니다.
- Notification Hub가 GA(General Availability) 상태로 전환 후 공식 버전으로 변경됩니다.
- 변경 가능한 부분은 이 문서에서 설명하는 API 엔드포인트, 인증, 요청 제한, 요청, 응답, 필드 등 모든 항목이 포함됩니다.
API 엔드포인트
리전 |
엔드포인트 |
Global |
https://notification-hub.api.nhncloudservice.com |
- Notification Hub는 리전 구분 없이 Global 엔드포인트를 사용합니다.
인증 및 권한
X-NHN-Authorization: {accessToken}
- 인증 토큰을 발급 받아 Notification Hub API 호출 시 X-NHN-Authorization 요청 헤더에 인증 토큰을 설정합니다.
인증 토큰 발급 예시
IntelliJ HTTP
POST https://oauth.api.nhncloudservice.com/oauth2/token/create
Content-Type: application/x-www-form-urlencoded
Authorization: Basic {{oauthAuthorization}}
cURL
curl -X POST "https://oauth.api.gov-nhncloudservice.com/oauth2/token/create" \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Authorization: Basic {{oauthAuthorization}}"
- oauthAuthorization은 User Access Key ID와 Secret Access Key를 USER_ACCESS_KEY_ID:SECRET_ACCESS_KEY로 합쳐 Base64 인코딩한 값입니다.
- User Access Key ID와 Secret Access Key는 로그인 후 오른쪽 상단의 메일 주소 > API 보안 설정에서 생성 및 관리할 수 있습니다.
- 인증 토큰 발급에 대한 자세한 내용은 사용자 가이드 > NHN Cloud > Public API > API 인증 > 인증 토큰 항목을 확인 부탁드립니다.
날짜와 시간 형식
- 날짜와 시간은 ISO 8601 확장 형식을 사용합니다.
- 사용 가능한 ISO 8601 형식은 다음과 같습니다.
- YYYY-MM-DDThh:mm+hh:mm
- YYYY-MM-DDThh:mmZ
- YYYY-MM-DDThh:mm:ss+hh:mm
- YYYY-MM-DDThh:mm:ssZ
- YYYY-MM-DDThh:mm:ss.sss+hh:mm
- YYYY-MM-DDThh:mm:ss.sssZ
- T는 날짜와 시간을 구분하는 구분자입니다.
- +hh:mm 또는 Z는 표준 시간대 지정자(Time Zone Designator) 를 나타냅니다.
- Notification Hub API 및 기능에서 초와 밀리초 단위는 사용되지 않습니다.
- API 응답에서 날짜와 시간은 YYYY-MM-DDThh:mm:ss.sss+09:000 형식으로 표기합니다.
응답 공통 정보
실패 응답 본문
성공 응답의 HTTP 상태 코드는 200 OK입니다.
{
"header": {
"isSuccessful": true,
"resultCode": 0,
"resultMessage": "SUCCESS"
}
}
실패 응답 본문
실패 응답의 HTTP 상태 코드는 4xx와 5xx입니다.
{
"header": {
"isSuccessful": false,
"resultCode": 400629,
"resultMessage": "실패에 대한 정보를 담고 있습니다."
}
}
이름 |
타입 |
설명 |
header.isSuccessful |
Boolean |
API 호출 성공 여부입니다. |
header.resultCode |
Integer |
결과 코드입니다. 성공은 0, 실패는 400000 이상의 값을 가집니다. |
header.resultMessage |
String |
결과 메시지입니다. 실패에 대한 정보를 담고 있습니다. |
- resultCode 앞자리 3자리는 HTTP 상태 코드와 동일하며, 뒷자리 3자리는 상세 코드입니다.
- 결과 메시지는 언제든지 변경될 수 있습니다. 결과 메시지를 비즈니스 로직에 사용하는 것은 권장하지 않습니다.
- 결과 메시지는 Accept-Language 요청 헤더에 따라 한국어, 영어, 일본어로 제공됩니다..
- API 호출 시 X-NC-ALWAYS-200-OK 요청 헤더에 값을 true로 설정하면, 실패 응답에도 HTTP 상태 코드 200 OK로 응답합니다.
요청 수 제한
- Notification Hub에서는 특정 클라이언트가 과도한 리소스 점유를 막고 서비스의 안정성을 보장하기 위해 API 요청 수를 제한합니다.
- API 요청 수는 초당 요청 수. 300RPS(Requests Per Second)으로 제한됩니다.
주의 사항
- 요청 수 계산은 클라이언트, 서버간 시간 차이, 네트워크 지연에 따라 다르게 측정되어 계산된 값이 다를 수 있습니다.
- 300RPS가 넘으면 서버는 HTTP 상태 코드 429(Too Many Requests) 응답으로 클라이언트의 요청을 거부합니다.
- 요청이 거부되었을 때 클라이언트가 즉시 재시도하면 서버의 요청 거부가 오랜 시간 동안 유지될 수 있습니다.
- 클라이언트는 요청이 거부되면 지수 백오프(Exponential Backoff) 처럼 재시도 간격을 늘려가며 호출하는 것을 권장합니다.
호출 예시
Notification Hub API 사용 가이드에서는 IntelliJ HTTP, cURL로 API 호출 예시를 제공합니다.
IntelliJ HTTP
- IntelliJ HTTP는 IntelliJ IDEA의 HTTP 클라이언트 플러그인으로 JetBrains IDEs 또는 명령줄에서 실행할 수 있습니다.
IntelliJ HTTP 환경 변수 설정 파일 예시(htt-client.env.json)
{
"default": {
"endpoint": "https://notification-hub.api.nhncloudservice.com",
"appKey": "앱키",
"accessToken": "인증 토큰"
}
}
cURL
- cURL은 명령줄에서 실행할 수 있는 커맨드 라인 도구로, 다양한 프로토콜을 지원합니다.
cURL 환경 변수 설정 예시
ENDPOINT=https://notification-hub.api.nhncloudservice.com
APP_KEY=앱키
ACCESS_TOKEN=인증 토큰