NAVER Cloud Platform API
  • PDF

NAVER Cloud Platform API

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

Note

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.

  1. Log in to NAVER CLOUD PLATFORM.
  2. 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.
  3. Check your Access Key ID and Secret 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 with https://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.

Was this article helpful?