-
Print
-
PDF
NAVER Cloud Platform API
-
Print
-
PDF
Overview
The application program interface (API) that supports the use of services and solutions provided by NAVER Cloud Platform is called NAVER Cloud Platform API.
This page describes what NAVER CLOUD PLATFORM APIs are and how to make an API request.
The Ncloud APIs are RESTful, using HTTP GET and POST methods, and the response format is XML and JSON. You can register, modify, delete, and get data by specifying required parameters, in order to run services and automate operation tools.
If an API request fails, it returns an error code and message.
How to make an API request
Follow the steps below to make an API request.
1. Create authentication key
2. Make API request
3. Handle response
4. Handle error
Create authentication key
Once an NAVER CLOUD PLATFORM account is created, one NAVER CLOUD PLATFORM API authentication key is issued by default. Go to My Page > Manage Account > Manage Auth Key in NAVER CLOUD PLATFORM to get the authentication key. Apart from the one automatically issued when an account is created, you can create one more authentication key. That is, an account can have up to two authentication keys.
You can disable or delete your authentication key if you don’t need it anymore.
An API authentication key consists of a pair of Access Key ID
and Secret Key
. They are passed as a parameter to authenticate an API.
- Log in to NAVER CLOUD PLATFORM.
- Go to My Page > Manage Account > Manage Auth Key, and click Create a New API Authentication Key.
- You can use a previously created authentication key, if there is any.
- Check your
Access Key ID
andSecret Key
in Manage Auth Key.
Make API request
AUTHPARAMS
Header | Description |
---|---|
x-ncp-apigw-timestamp | It is the number of milliseconds that have elapsed since January 1, 1970 00:00:00 UTC. * If the time difference with the API Gateway server is more than 5 minutes, the request is considered invalid. |
x-ncp-iam-access-key | * Access Key ID issued from the NAVER CLOUD PLATFORM Portal or Sub Account. |
x-ncp-apigw-signature-v2 | * Signature used to encrypt the body of the example with the “secret key” that maps with the “access key.” * The HMAC encryption algorithm is HMAC SHA256. |
- AUTHPARAMS request example
curl -i -X GET \
-H "x-ncp-apigw-timestamp:1505290625682" \
-H "x-ncp-iam-access-key:D78BB444D6D3C84CA38A" \
-H "x-ncp-apigw-signature-v1:WTPItrmMIfLUk/UyUIyoQbA/z5hq9o3G8eQMolUzTEo=" \
'https://example.apigw.ntruss.com/photos/puppy.jpg?query1=&query2'
- Create a signature
- Add a new line with \n.
- Create a StringToSign appropriate for your request, encrypt it with your secret key and the HMACSHA256 algorithm and encode it with Base64.
- Use this value as
x-ncp-apigw-signature-v2
. - Caution: The x-ncp-apigw-timestamp value of the request header and the timestamp of StringToSign must be the same value.
Request | StringToSign |
---|---|
GET /photos/puppy.jpg?query1=&query2 x-ncp-apigw-timestamp={timestamp} x-ncp-iam-access-key={accesskey} x-ncp-apigw-signature-v1={signature} |
GET /photos/puppy.jpg?query1=&query2 {timeStamp} {accessKey} |
- Request example
public String makeSignature() {
String space = " "; // one space
String newLine = "\n"; // new line
String method = "GET"; // method
String url = "/photos/puppy.jpg?query1=&query2"; // url (include query string)
String timestamp = "{timestamp}"; // current timestamp (epoch)
String accessKey = "{accessKey}"; // access key id (from portal or Sub Account)
String secretKey = "{secretKey}";
String message = new StringBuilder()
.append(method)
.append(space)
.append(url)
.append(newLine)
.append(timestamp)
.append(newLine)
.append(accessKey)
.toString();
SecretKeySpec signingKey = new SecretKeySpec(secretKey.getBytes("UTF-8"), "HmacSHA256");
Mac mac = Mac.getInstance("HmacSHA256");
mac.init(signingKey);
byte[] rawHmac = mac.doFinal(message.getBytes("UTF-8"));
String encodeBase64String = Base64.encodeBase64String(rawHmac);
return encodeBase64String;
}
/*
https://code.google.com/archive/p/crypto-js/
https://storage.googleapis.com/google-code-archive-downloads/v2/code.google.com/crypto-js/CryptoJS%20v3.1.2.zip
*/
/*
CryptoJS v3.1.2
code.google.com/p/crypto-js
(c) 2009-2013 by Jeff Mott. All rights reserved.
code.google.com/p/crypto-js/wiki/License
*/
<script type="text/javascript" src="./CryptoJS/rollups/hmac-sha256.js"></script>
<script type="text/javascript" src="./CryptoJS/components/enc-base64.js"></script>
function makeSignature() {
var space = " "; // one space
var newLine = "\n"; // new line
var method = "GET"; // method
var url = "/photos/puppy.jpg?query1=&query2"; // url (include query string)
var timestamp = "{timestamp}"; // current timestamp (epoch)
var accessKey = "{accessKey}"; // access key id (from portal or Sub Account)
var secretKey = "{secretKey}"; // secret key (from portal or Sub Account)
var hmac = CryptoJS.algo.HMAC.create(CryptoJS.algo.SHA256, secretKey);
hmac.update(method);
hmac.update(space);
hmac.update(url);
hmac.update(newLine);
hmac.update(timestamp);
hmac.update(newLine);
hmac.update(accessKey);
var hash = hmac.finalize();
return hash.toString(CryptoJS.enc.Base64);
}
import sys
import os
import hashlib
import hmac
import base64
import requests
import time
def make_signature():
timestamp = int(time.time() * 1000)
timestamp = str(timestamp)
access_key = "{accessKey}" # access key id (from portal or Sub Account)
secret_key = "{secretKey}" # secret key (from portal or Sub Account)
secret_key = bytes(secret_key, 'UTF-8')
method = "GET"
uri = "/photos/puppy.jpg?query1=&query2"
message = method + " " + uri + "\n" + timestamp + "\n"
+ access_key
message = bytes(message, 'UTF-8')
signingKey = base64.b64encode(hmac.new(secret_key, message, digestmod=hashlib.sha256).digest())
return signingKey
function makeSignature() {
nl=$'\\n'
TIMESTAMP=$(echo $(($(date +%s%N)/1000000)))
ACCESSKEY="{accessKey}" # access key id (from portal or Sub Account)
SECRETKEY="{secretKey}" # secret key (from portal or Sub Account)
METHOD="GET"
URI="/photos/puppy.jpg?query1=&query2"
SIG="$METHOD"' '"$URI"${nl}
SIG+="$TIMESTAMP"${nl}
SIG+="$APIKEY"${nl}
SIG+="$ACCESSKEY"
SIGNATURE=$(echo -n -e "$SIG"|iconv -t utf8 |openssl dgst -sha256 -hmac $SECRETKEY -binary|openssl enc -base64)
}
Handle response
- For responses to service API calls, please refer to the API guide of each service.
Handle error
- For error codes for service API calls, please refer to the API guide of each service.
API error examples
-
For user errors:
HTTP Response Code = 400
<responseError> <returnCode>900</returnCode> <returnMessage> Required field is not specifie4. location : serverImageProductCode. </returnMessage> </responseError>
-
For authentication errors:
HTTP Response Code = 401
<responseError> <returnCode>801</returnCode> <returnMessage>Signature is invalided</returnMessage> </responseError>
Common Error Code
- When
responseFormatType=xml
is set
<?xml version='1.0' encoding='UTF-8' ?>
<Message>
<error>
<errorCode>210</errorCode>
<message>Permission Denied</message>
</error>
</Message>
- When
responseFormatType=json
is set (default)
{
"error":{
"errorCode":"210",
"message":"Permission Denied"
}
}
Error Codes
HTTP status code | Error code | Error message | Description |
---|---|---|---|
400 | 100 | Bad Request Exception | Request error in protocol (https) or encoding (UTF-8). |
401 | 200 | Authentication Failed | Authentication failed. |
401 | 210 | Permission Denied | No permissions. |
404 | 300 | Not Found Exception | No permissions. |
429 | 400 | Quota Exceeded | Quota exceeded. |
429 | 410 | Throttle Limited | Rate exceeded. |
429 | 420 | Rate Limited | Rate exceeded. |
413 | 430 | Request Entity Too Large | Request entity size exceeded. |
503 | 500 | Endpoint Error | Endpoint connection error |
504 | 510 | Endpoint Timeout | Endpoint connection timeout. |
500 | 900 | Unexpected Error | Exception unhandled. |
Supported APIs and SDKs
NAVER CLOUD PLATFORM enables you to control various services such as Server, Load Balancer, Auto Scaling, Monitoring, Security, GeoLocation and Hash Filter with APIs. The APIs are RESTful, and their response format is XML and JSON. You can register, modify, delete, and get data by specifying required parameters, in order to run services and automate operation tools.
Service | API | SDK |
---|---|---|
Server | Server API | ncloud_server.zip |
Load Balancer | Load Balancer API | ncloud_loadbalancer.zip |
Auto Scaling | Auto Scaling API | ncloud_autoscaling.zip |
Monitoring | Monitoring API | ncloud_monitoring.zip |
Security | Security API | ncloud_security.zip |
GeoLocation | GeoLocation API | ncloud_geolocation.zip |
CDN+ | CDN+ API | ncloud_cdn_v2.zip |
Cloud DB | Cloud DB API | ncloud_clouddb_v2.zip |
Cloud Outbound Mailer | Cloud Outbound Mailer API | ncloud_outboundmailer.zip |
Ncloud APIs Release Note
NAVER CLOUD PLATFORM’s Ncloud APIs have been improved since the first release.
Available versions of the Ncloud APIs
Currently, the following 2 versions are available: Ncloud APIs V1, and Ncloud APIs V2
We recommend you to use the Ncloud APIs V2, which comes with enhanced usability; the Ncloud APIs V1 will be deprecated with prior notice.
-
Ncloud APIs V1
: This version of APIs is available via the new API Gateway that supports enhanced API management, using the domain that starts withhttps://ncloud.apigw.ntruss.com/
. The Ncloud APIs V1 requires an API key issued by the API Gateway for authentication.: As the Ncloud APIs V1 requires an API key issued by the API Gateway, you should apply for the API Gateway service. (Note that you will not be charged for the API Gateway service since you only get an API key.)
-
Ncloud APIs V2
: The operations and how to make API requests in the Ncloud APIs V2 are the same as those in the Ncloud APIs V1, except that the V2 does not require an API key. Therefore, you do not need to apply for API Gateway.: Since some services require an API key, please refer to the API specifications of each service.
Authentication methods
-
API key authentication method
-
This method requires an API key for each account for authentication. Go to API Gateway > API Keys in NAVER CLOUD PLATFORM’s console and click Create API Key to get an
API key
. -
For the Ncloud APIs V1, you must include your API key in the authorization and request headers to make an API request.
-
For the Ncloud APIs V2, you do not need to include your API key in the authorization or request header to make an API request.
Ncloud API documentations
-
Service | Ncloud APIs V1: (API Key authentication) | Ncloud APIs V2: (No API Key authentication) |
---|---|---|
Server | Go to documentation | Server API |
Load Balancer | Go to documentation | Load Balancer API |
Auto Scaling | Go to documentation | Auto Scaling API |
Monitoring | Go to documentation | Monitoring API |
Security | Go to documentation | Security API |
GeoLocation | Go to documentation | GeoLocation API |
CDN | Go to documentation | CDN API |
Cloud DB | Go to documentation | Cloud DB API |
Cloud Outbound Mailer | Go to documentation | Cloud Outbound Mailer API |
(Since some services require an API key, please refer to the API specifications of each service.)
Ncloud APIs deprecation schedule
- The Ncloud APIs V1 will be deprecated as of Dec. 31, 2021, and will no longer be available after that.