Quick start

Get to know APIs

SCloud API adopts an instructional style, and each API request includes an instruction (Action), instruction parameters and authentication information (PublicKey, Signature).

Common parameters

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

Parameter name	Type		Required
Action	string	The corresponding API instruction name, the current API is `DescribeUHostInstance`	Yes
PublicKey	string	The user’s public key, available from Console fetch	Yes
Signature	string	According to the public key and API The user signature generated by the directive is found in 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 or not depends on the definition of the specific API.

The parameter name	Type	Description	Required
Region	string	See List of Regions and Availability Zones	Yes
Zone	string	See List of Regions and Availability Zones	Yes
ProjectId	string	Project ID (example: `org-04ibqy`), This field, by default, is empty and is only required when the account is a Sub-Account	No

Public Response

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

Field name	Type	Describe	Required
RetCode	int	Returns a status code, with `0` for success and failure for `non-0`	Yes
Action	string	The name of the operation instruction	Yes
Message	string	Returns an error message that provides detailed description information when RetCode is non-0	No
ULHostId	string	Instance ID	Yes

Error Code Description

RetCode	Description
110	API response timed out (60 seconds)
130	API gateway or authentication service exception
150	The service is currently unavailable, we are working hard to restore it, please try again later
153	API requests are limited
160	The 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	Item does not exist
293	Availability zone permission error
294	Access to IP is denied
295	Security lock verification failed
299	IAM permission verification failed

Quick start

Preparation

Get the API access address
Get the API key, including PublicKey and PrivateKey, from the UAPI console
If the resource to be operated belongs to a certain region, obtain the list of regions and availability zones
If the account belongs to a sub-account, or needs to operate a specific project, get the project ID

Make a request

You can initiate requests to the API access address in various ways, including clients such as cURL and Postman, as well as UAPI browsers, CLIs, SDKs, etc. It is recommended to use a UAPI browser. After the request is constructed and initiated, the SDK sample can be automatically generated.

SCloud API supports two methods of GET / POST, and two request methods of 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 assumptions

In this example assume:

PublicKey  = 'john.doe@example.com1296235120854146120'
PrivateKey = '46f09bb9fab4f12dfc160dae12273d5332b5debe'

Suppose the user request parameters are as follows:

{
    "Action"     :  "DescribeUHostInstance",
    "Region"     :  "vn-sng",
    "Limit"      :  10
}

Calculate signature

Refer to the signature algorithm document, the calculated Signature is 52fc1191f026532c9100946c6a863a90d5f766ed.

Construct request

Fill in the PublicKey and Signature into the request parameters, and the constructed request is finally:

curl -X POST \
  https://api.scloud.sg \
  -H 'Content-Type: application/json' \
  -d '{
      "Action"     :  "DescribeUHostInstance",
      "Limit"      :  10,
      "PublicKey"  :  "john.doe@example.com1296235120854146120",
      "Region"     :  "vn-sng",
      "Signature"  :  "52fc1191f026532c9100946c6a863a90d5f766ed"
  }'