Ncloud API
  • PDF

Ncloud API

  • PDF

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.

Service SDK download link
Server ncloud_server.zip
Load Balancer ncloud_loadbalancer.zip
Auto Scaling ncloud_autoscaling.zip
Monitoring ncloud_monitoring.zip
Security ncloud_security.zip
GeoLocation ncloud_geolocation.zip
CDN+ ncloud_cdn_v2.zip
Cloud DB ncloud_clouddb_v2.zip
Cloud Outbound Mailer ncloud_outboundmailer.zip

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.

Note
  • For more information on creating accounts and creating authentication keys from the NAVER Cloud Platform portal, refer to Sign up and Security settings of the Portal and console guide.
  • If you'd like to know more about creating or managing authentication keys from NAVER Cloud Platform's Sub Account, refer to the Sub Account Guide.
Caution

Please note that disabling or deleting an authentication key makes it recognized as an invalid key.

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.

Header Description
x-ncp-apigw-timestamp - The elapsed time in milliseconds since January 1, 1970 Cordinated Universal Time (UTC).
- If the time difference with the API Gateway server is more than 5 minutes, it is considered as an invalid request.
x-ncp-iam-access-key - Access key ID issued from the NAVER Cloud Platform portal or Sub Account
x-ncp-apigw-signature-v2 - Signature value encrypted with the secret key whose body is mapped the access key ID
- HmacSHA256 is used for the HMAC encryption algorithm

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

The x-ncp-apigw-timestamp value of the request header and the timestamp of the 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-v2={signature}
GET /photos/puppy.jpg?query1=&query2
{timeStamp}
{accessKey}

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.

HTTP status code Error code Error message Description
400 100 Bad Request Exception Request errors, such as protocol (https) and encoding (UTF-8)
401 200 Authentication Failed Authentication failure
401 210 Permission Denied No permission
404 300 Not Found Exception No permission
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 Errors not handled as exceptions

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.

Note
  • API keys can be created through API Gateway of NAVER Cloud Platform. For more information on creating API keys, refer to the API Gateway Guide.
  • When issuing API keys from API Gateway, no additional fees are charged for API Gateway since only API keys are issued.

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.


Was this article helpful?