Common Information on Notification Hub API v1.0
Notification > Notification Hub > API v1.0 User Guide > Common Information
Caution
- Notification Hub API v1.0 is currently in an alpha state, is not stabilized, and experimental features may be added or removed.
- The API is subject to change at any time to improve the service, and changes may not be announced in advance.
- Notification Hub will change to the official version after it is in General Availability (GA).
- The parts that are subject to change include everything described in this document: API endpoints, authentication, request limits, requests, responses, fields, etc.
API Endpoint
Region |
Endpoint |
Global |
https://notification-hub.api.nhncloudservice.com |
- Notification Hub uses global endpoints regardless of regions.
Authentication and Authorization
X-NHN-Authorization: Bearer {accessToken}
- Obtain an issued authorization token and set it in the X-NHN-Authorization request header when calling the Notification Hub API.
Example of Authentication Token Issuance
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.nhncloudservice.com/oauth2/token/create" \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Authorization: Basic {{oauthAuthorization}}"
- oauthAuthorization is the Base64-encoded value of the User Access Key ID and Secret Access Key combined with USER_ACCESS_KEY_ID:SECRET_ACCESS_KEY.
- User Access Key ID and Secret Access Key can be created and managed in API Security Settings in thetop right corner after logging in.
- For more information about authentication token issuance, please refer to User Guide > NHN Cloud > Public API > API Authentication > Authentication Token.
- Dates and times use the ISO 8601 extended format.
- The following ISO 8601 formats are available
- 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 is the separator between date and time.
- +hh:mm or Z represents the Time Zone Designator.
- The units of seconds and milliseconds are not used in the Notification Hub API and features.
- In the API response, the date and time are represented in the format YYYY-MM-DDThh:mm:ss.sss+09:000.
Prefix and Single-Character Wildcard Search
List lookups support prefix and single character wildcard searches for non-personal information lookup criteria.
Prefix Search
- Prefix search searches for values that begin with a specific string.
- Request Example
- Search for templates whose template names begin
with _ad_
.
GET /message/v1.0/templates?templateName=Advertising
- Search results: Ad-1, Ad-2, Ad-3, etc.
Single Character Wildcard Search
- A single-character wildcard search searches for any character in a specific location.
- Request Example
- Search for templates with template names ending in
-1
.
GET /message/v1.0/templates?templateName=__-1
- Search results: Ads-1, General-1, Announcements-1, etc.
[Failure response body]
The HTTP status code for a successful response is 200 OK.
{
"header": {
"isSuccessful": true,
"resultCode": 0,
"resultMessage": "SUCCESS"
}
}
[Failure response body]
The HTTP status codes for the failure response are 4xx and 5xx.
{
"header": {
"isSuccessful": false,
"resultCode": 400629,
"resultMessage": "Contains information about the failure."
}
}
Name |
Type |
Description |
header.isSuccessful |
Boolean |
API call is successful or not |
header.resultCode |
Integer |
The result code. Success has a value of 0 and failure has a value of 400000 or higher. |
header.resultMessage |
String |
The result message, which contains information about the failure. |
- The first three digits of the resultCode are the same as the HTTP status code, and the last three digits are the detail code.
- The resulting messages are subject to change at any time. We do not recommend using the result messages for business logic.
- The result message is available in Korean, English, and Japanese, depending on the Accept-Language request header.
- If you set the value to true in the X-NC-ALWAYS-200-OK request header when calling the API, it will respond with HTTP status code 200 OK on failure responses.
Request Number Limit
- Notification Hub limits the number of API requests to prevent certain clients from taking up excessive resources and to ensure the reliability of the service.
- The number of API requests per second. It is limited to 300 Requests Per Second (RPS).
Caution
- The request count is measured differently by the client, the time difference between the server and the client, and network latency, so the calculated value may vary.
- If the number of requests exceeds 300 RPS, the server will reject the client's request with an HTTP status code 429 (Too Many Requests) response.
- If the client retries immediately when a request is rejected, the server's rejection of the request might persist for a long time.
- It is recommended that the client invoke an increasing retry interval, such as an exponential backoff, when a request is rejected.
Example of API Calls
The Notification Hub API User Guide provides examples of API calls with IntelliJ HTTP and cURL.
IntelliJ HTTP
- IntelliJ HTTP is an HTTP client plugin for IntelliJ IDEA that can be run from JetBrains IDEs or from the command line.
Example of IntelliJ HTTP environment variable configuration file (htt-client.env.json)
{
"default": {
"endpoint": "https://notification-hub.api.nhncloudservice.com",
"appKey": "App key",
"accessToken": "Authentication token"
}
}
cURL
- cURL is a command-line tool that can be run from the command line and supports a variety of protocols.
Example of cURL environment variable settings
ENDPOINT=https://notification-hub.api.nhncloudservice.com
APP_KEY=App key
ACCESS_TOKEN=Authorization token