Ncloud API

Available in Classic and VPC

This guide describes the support information of the NAVER Cloud Platform API (Ncloud API), as well as common API call and authentication methods.

Supported APIs and SDKs

The NAVER Cloud Platform API can control various featues of services such as Server, Load Balancer, Auto Scaling, Monitoring, Security, GeoLocation, and Hash Filter. Please check the information of supported APIs and SDKs.

API

All APIs other than compatible APIs and linkage APIs are applicable. For the list of detailed APIs supported by each service, refer to the API guide of each service.

SDK

The list of SDKs supported by each service and their download links are as follows.

Call API

The NAVER Cloud Platform API is provided in the RESTful API method, and it responds in XML and JSON format. According to the action, parameter values can be entered, registered, modified, deleted, and searched. They can also be utilized for automation of service and operation tools. It is used through GET/POST method calls in the HTTP format, and returns an error code and message when an invalid call is made. The following describes the steps to call the NAVER Cloud Platform API.

1. Create authentication key
2. Create header
3. Call

1. Create authentication key

To use the NAVER Cloud Platform API, you need to first create an authentication key. The authentication key is a tool that identifies users so that only users with permissions can call the API. It consists a pair of Access Key and Secret Key. Access Key and Secret Key are used as parameters that are passed during API authentication.
One NAVER Cloud Platform API authentication key is automatically created upon creation of a NAVER Cloud Platform account. In addition to the automatically created authentication key, users can create it manually from the portal, so up to 2 authentication keys can be issued per user.
You can manage and view issued authentication keys, or create an authentication key from My Page > Manage account > Manage authentication key in the NAVER Cloud Platform portal.

2. Create header

You can create a header using the created authentication key. The header includes parameters related to authentication (AUTHPARAMS). The header described here is a common header of APIs belonging to the NAVER Cloud Platform API, and the header configuration of APIs for each service may differ slightly. For the header configuration of APIs for each service, refer to the API guide of each service.
The following describes the common header of the NAVER Cloud Platform API.

The following is an AUTHPARAMS request example using the created header.

curl -i -X GET \
-H "x-ncp-apigw-timestamp:1505290625682" \
-H "x-ncp-iam-access-key:D78BB444D6D3C84CA38D" \
-H "x-ncp-apigw-signature-v2:WTPItrmMIfLUk/UyUIyoQbA/z5hq9o3G8eQMolUzTEa=" \
'https://example.apigw.ntruss.com/photos/puppy.jpg?query1=&query2'

Create signature

The signature is the value that goes into the last field (x-ncp-apigw-signature-v2) of the common header. The following describes how to create a signature.

• Use \n as the line break text.
• Create StringToSign according to the request, encrypt in the HmacSHA256 algorithm with the secret key, and then encode with Base64.
• Use the encoded value as x-ncp-apigw-signature-v2.

The examples of signature creation by language are as follows.

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+="$ACCESSKEY"

	SIGNATURE=$(echo -n -e “$SIG“|iconv -t utf8 |openssl dgst -sha256 -hmac $SECRETKEY -binary|openssl enc -base64)
}

3. Call

Call the API based on the content of Steps 1 to 3. The results of API calls can be categorized into success and failure. If the response is successful, check the returned result. If the response fails, an error code is returned. Check the returned error code and try the call again.

Success

For response handling methods for service API calls, refer to the response information in the API guide of each service.

Failure

Error codes returned from failed calls include common error codes and service-specific error codes. For more information on service-specific error codes, refer to error codes in the API guide of each service.
Common error codes are displayed in the JSON format by default. Messages and descriptions for each common error code are as follows.

Examples of common error codes are as follows.

• When the request parameter is Content-type: application/json

  {
   "error":{
      "errorCode":"210",
      "message":"Permission Denied"
   }
   }
  

• When the request parameter is Content-type: application/xml

  <?xml version='1.0' encoding='UTF-8' ?>
  <Message>
      <error>
       <errorCode>210</errorCode>
       <message>Permission Denied</message>
   </error>
  </Message>
  

API authentication method

The V1 version of the NAVER Cloud Platform API used the API key authentication method, where keys are issued by account and used for authentication. Thus, an API key had to be included in the header when calling the API.

However, starting on January 1, 2022, the service for the V1 version has been terminated, and the V2 version, which doesn't require application of API keys, is provided. While the operation and basic calling method of the V2 version are the same as the V1 version, you don't have to include the API key to the header when calling the API, freeing you up from having to request subscription to API Gateway, so it is easier to use.
However, the authentication method using an API key may be absolutely necessary in certain services, so check if the application of an API key is required by referring to the API guide of each service.