Ncloud API
    • PDF

    Ncloud API

    • PDF

    Article Summary

    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.

    ServiceSDK download link
    Serverncloud_server.zip
    Load Balancerncloud_loadbalancer.zip
    Auto Scalingncloud_autoscaling.zip
    Monitoringncloud_monitoring.zip
    Securityncloud_security.zip
    GeoLocationncloud_geolocation.zip
    CDN+ncloud_cdn_v2.zip
    Cloud DBncloud_clouddb_v2.zip
    Cloud Outbound Mailerncloud_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.

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

    RequestStringToSign
    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 codeError codeError messageDescription
    400100Bad Request ExceptionRequest errors, such as protocol (https) and encoding (UTF-8)
    401200Authentication FailedAuthentication failure
    401210Permission DeniedNo permission
    404300Not Found ExceptionNo permission
    429400Quota ExceededQuota exceeded
    429410Throttle LimitedRate exceeded
    429420Rate LimitedRate exceeded
    413430Request Entity Too LargeRequest entity size exceeded
    503500Endpoint ErrorEndpoint connection error
    504510Endpoint TimeoutEndpoint connection timeout
    500900Unexpected ErrorErrors 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?

    Changing your password will log you out immediately. Use the new password to log back in.
    First name must have atleast 2 characters. Numbers and special characters are not allowed.
    Last name must have atleast 1 characters. Numbers and special characters are not allowed.
    Enter a valid email
    Enter a valid password
    Your profile has been successfully updated.