Constructing Requests

This section describes the structure of a RESTful API request, and uses the API for creating customers of HUAWEI CLOUD partners as an example to describe how to call an API.

Request URI

A request URI consists of the following:

{URI-scheme}://{Endpoint}/{resource-path}?{query-string}

Although the request URI is included in the request header, most languages or frameworks require that it be transmitted separately from the request message. Therefore, the request URI is listed independently.

**Table 1** URI parameter description
Parameter	Description
URI-scheme	Protocol used to transmit requests. All APIs use HTTPS.
Endpoint	Specifies the domain name or IP address of the server bearing the REST service endpoint. The operations API endpoint for customer is bss-intl.myhuaweicloud.com. NOTE: This endpoint is a global endpoint and can be used for all regions in Huawei Cloud (International Website). TLS 1.2 supported.
resource-path	Resource path, that is, the API access path. Obtain the path from the URI of the API. For example, the resource-path of the API for creating a customer is /v2/partners/sub-customers.
query-string	Query parameter, which is optional. Ensure that a question mark (?) is included before each query parameter that is in the format of "Parameter name=Parameter value". For example, ?limit=10 indicates that a maximum of 10 data records will be displayed.

For example, to obtain the request URI for creating a customer, obtain the corresponding resource-path (/v2/partners/sub-customers). Then, construct the URI as follows:

https://bss-intl.myhuaweicloud.com/v2/partners/sub-customers

Click to enlarge

To simplify URI display, each API is provided with only resource-path and the request method. This is because the URI-scheme value of all APIs is HTTPS, and the endpoints in a region are the same. Therefore, the two parts are omitted.

Request Method

The HTTP protocol defines the following request methods that can be used to send a request to the server:

**Table 2** HTTP methods
Method	Description
GET	Requests a server to return a specified resource.
PUT	Requests a server to update a specified resource.
POST	Requests a server to add a resource or perform a special operation.
DELETE	Requests a server to delete a specified resource (for example, an object).
HEAD	Requests a server resource header.
PATCH	Requests a server to update partial content of a specified resource. If the resource does not exist, the PATCH method is used to create a new resource.

As shown in the URI for creating a customer, the request method is POST. The request URI is as follows:

    
         POST https://bss-intl.myhuaweicloud.com/v2/partners/sub-customers

Request Header

You can also add additional fields to the request header, for example, the fields required by a specified URI and an HTTP method. Table 3 lists common request header fields.

**Table 3** Common request header fields
Field	Description	Mandatory	Example
Host	Specifies the server domain name and port number of the resources being requested. The value can be obtained from the URL of the service API. If the port number is not specified, the default port is used. The default port number for https is 443.	No This field is mandatory only when AK/SK is used for authentication.	bss-intl.myhuaweicloud.com or bss-intl.myhuaweicloud.com:443
Content-Type	Specifies the request body MIME type. You are advised to use the default value application/json. For an object or image upload API, the value varies depending on the flow type.	Yes	application/json
Content-Length	Length of the request body. The unit is byte.	No	3495
X-Auth-Token	Specifies the user token. For details about how to obtain a token, see Token Authentication.	No This field is mandatory only when the token is used for authentication.	The following is part of an example token: MIIPAgYJKoZIhvcNAQcCoIIO8zCCDu8CAQExDTALBglghkgBZQMEAgEwgg1QBgkqhkiG9w0BBwGggg1BBIINPXsidG9rZ

In addition to supporting authentication using tokens, APIs support authentication using AK/SK, which uses SDK to sign a request. During the signature, the Authorization (signature authentication) and X-Sdk-Date (time when a request is sent) headers are automatically added to the request.

For more details, see Authentication Using AK/SK in Authentication.

The request of the interface for creating a customer is as follows after the request header is added:

POST https://bss-intl.myhuaweicloud.com/v2/partners/sub-customers 
Content-Type: application/json
X-Auth-Token: MIIPAgYJKoZIhvcNAQcCo...ggg1BBIINPXsidG9rZ

(Optional) Request Body

This part is optional. A request body is often sent in a structured format (for example, JSON or XML) as defined in the Content-Type header field. If the request body contains Chinese characters, these characters must be coded in UTF-8.

Request bodies vary with API. Some APIs do not require a request body, such as the APIs requested using the GET and DELETE methods.

In the case of the API used to create a customer, you can obtain the required request parameters and parameter description from the API request. The following is a request carrying the message body, where the request parameters vary with actual condition.

    
         POST  https://bss-intl.myhuaweicloud.com/v2/partners/sub-customers HTTP/1.1
Content-Type: application/json
X-Auth-Token: MIIPAgYJKoZIhvcNAQcCo...ggg1BBIINPXsidG9rZ

{
  "domain_name": "test",
  "email": "xxx@huawei.com",
  "verification_code": "253xxx",
  "domain_area": "HK",
  "xaccount_id": "35reyxxxx",
  "xaccount_type": "xxx_IDP",
  "password": "xxxxxxx",
  "is_close_market_ms": "true",
  "cooperation_type": "1"
  
}