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.

Date and Time Formats

  • 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.

List lookups support prefix and single character wildcard searches for non-personal information lookup criteria.

  • 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.
  • 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.

Response Common Information

[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

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
TOP