Quick Start

Recognition API

Our API adopts an imperative style. Each API request contains an instruction (Action), instruction parameters and authentication information (PublicKey, Signature).

Public Parameters

Public parameters are parameters that must be given when operating all APIs. They are usually displayed at the top of all parameters in the API document.

Parameter Name	Type	Description Information	Required
Action	string	Corresponding API Command Name，For example `DescribeUHostInstance`	Yes
PublicKey	string	User public key, which can be obtained from Console (opens in a new tab)	Yes
Signature	string	User signature generated based on public key and API command, see Signature Algorithm	Yes

General Parameters

General parameters are parameters that may be used by most APIs and have consistent meanings. Whether they need to be given depends on the definition of the specific API.

Parameter Name	Type	Description Information
Region	string	Region. See Region and Availability Zone List
Zone	string	Availability zone. See Region and Availability Zone List
ProjectId	string	Project ID. If not filled in, it is the default item, and the sub-account must be filled in. See Get project ID

Public Response

The public response is a response style that all APIs follow uniformly, including an instruction response name (Action), a status code to identify whether the API is successful (RetCode), and when an error is encountered, the error message returned (Message ).

Field Name	Type	Description Information	Required
RetCode	int	Return status code. If it is 0, it means successful return. If it is not 0, it means failure.	Yes
Action	string	Operation command name	Yes
Message	string	Returns an error message, providing detailed description when `RetCode` is non-zero	No

Error Code Explanation

RetCode	Description
110	API response timeout（60Second）
130	API gateway or authentication service is abnormal
150	The service is currently unavailable, we are working hard to recover, please try again later
153	API request is throttled
160	Key parameter Action is missing, please provide complete parameters
161	Action does not exist
170	Missing signature
171	Signature error
172	User does not exist
174	Token does not exist
292	The project does not exist
293	Availability zone permission error
294	Access IP rejected
295	Security lock verification failed
299	IAM permission verification failed

Quick Start

Preparation Work

Obtain API Access Address
From Control Panel (opens in a new tab) Obtain API Key, Including PublicKey And PrivateKey
If the resource to be operated belongs to a certain region, Get the list of regions and availability zones
If the account is a sub-account, or need to operate a specific project, Fetch Project ID

Initiate Request

You can make requests to the API access address in a variety of ways, including clients such as cURL (opens in a new tab), Postman (opens in a new tab), etc.

Our API supports two methods: GET / POST, and supports two request methods: application/json and application/x-www-form-urlencoded.

This article takes cURL POST JSON as an example to describe how to construct and initiate an HTTP request.

Data Assumption

In this example it is assumed:

PublicKey  = 'someone@example.com1296235120854146120'
PrivateKey = '46f09bb9fab4f12dfc160dae12273d5332b5debe'

Assume that the user request parameters are as follows:

{
    "Action"     :  "DescribeUHostInstance",
    "Region"     :  "cn-bj2",
    "Limit"      :  10
}

Calculate Signature

Please refer to the Signature Algorithm document. The calculated Signature is cba5cf5ec4d4233d206b1b54951e3787350a642f.

Construct Request

Fill in the request parameters with PublicKey and Signature, and the constructed request will finally be:

curl -X POST \
  https://api.surfercloud.com \
  -H 'Content-Type: application/json' \
  -d '{
      "Action"     :  "DescribeUHostInstance",
      "Limit"      :  10,
      "PublicKey"  :  "someone@example.com1296235120854146120",
      "Region"     :  "cn-bj2",
      "Signature"  :  "cba5cf5ec4d4233d206b1b54951e3787350a642f"
  }'

Index Signature Algorithm