# 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](https://console.scloudsg.com/uaccount/api_manage)| **Yes** |
| **Signature**  | string  | User signature generated based on public key and API command, see [Signature Algorithm](/docs/api/summary/signature) | **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](/docs/api/summary/regionlist) |
| **Zone** | string | Availability zone. See [Region and Availability Zone List](/docs/api/summary/regionlist) |
| **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](/docs/api/summary/get_project_list) |

### 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

1. Obtain [API Access Address](/docs/api/summary/gateway)
2. From [Control Panel](https://console.scloudsg.com/uaccount/api_manage) Obtain API Key, Including `PublicKey` And `PrivateKey`
3. If the resource to be operated belongs to a certain region, [Get the list of regions and availability zones](/docs/api/summary/regionlist)
4. If the account is a sub-account, or need to operate a specific project, [Fetch Project ID](/docs/api/summary/regionlist)

### Initiate Request

You can make requests to the API access address in a variety of ways, including clients such as [cURL](https://curl.haxx.se/), [Postman](https://www.postman.com/), 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:

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

**Calculate Signature**

Please refer to the [Signature Algorithm](/docs/api/summary/signature) document. The calculated `Signature` is **4201919d267504385deb93af19e0197870fed36b**.

**Construct Request**

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

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