Constructing a Request

Updated on 2023-12-13 GMT+08:00

View PDF

This section describes the structure of a REST API, and uses the IAM API for obtaining a user token as an example to describe how to call an API. The obtained token is used to authenticate the calling of other APIs.

Request URI

A request URI is in the following format:

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

Although a request URI is included in a request header, most programming languages or frameworks require the request URI to be separately transmitted, rather than being conveyed in a request message.

**Table 1** URI parameter description
Parameter	Description
URI-scheme	Protocol used to transmit requests. All APIs use HTTPS.
Endpoint	Domain name or IP address of the server bearing the REST service endpoint. Obtain the value from Endpoints. For example, the endpoint of IAM in region CN-Hong Kong is iam.ap-southeast-1.myhuaweicloud.com.
resource-path	Resource path, that is, API access path. Obtain the value from the URI of the API. For example, the resource-path of the API for obtaining a user token is /v3/auth/tokens.
query-string	(Optional) Query parameter. Not all APIs have a query parameter. Ensure that a question mark (?) is included before a query parameter that is in the format of ?Parameter name=Parameter value. For example, ?limit=10 indicates that a maximum of 10 pieces of data is to be viewed.

For example, to obtain the IAM token in region CN-Hong Kong, obtain the endpoint (iam.ap-southeast-1.myhuaweicloud.com) of this region and resource-path (/v3/auth/tokens) in the URI of the API for obtaining a user token. Then, assemble the fields as follows:

https://iam.ap-southeast-1.myhuaweicloud.com/v3/auth/tokens

Figure 1 Example URI

NOTE:

To simplify the URI display, each API provides 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

HTTP-based request methods, which are also called operations or actions, specify the type of operations that you are requesting. Table 2 describes the methods supported by the REST APIs of Image Search.

**Table 2** HTTP methods
Method	Description
GET	Requests the server to return a specified resource.
PUT	Requests the server to update a specified resource.
POST	Requests the server to add a resource or perform a special operation.
DELETE	Requests the server to delete a specified resource, for example, an object.
HEAD	Request a server resource header.
PATCH	Requests the server to apply partial modifications to a resource. If the resource does not exist, the PATCH method may create a resource.

For example, in the URI for obtaining a user token, the request method is POST, and the request is as follows:

POST https://iam.ap-southeast-1.myhuaweicloud.com/v3/auth/tokens

Request Header

You can add additional fields, for example, the fields required by a specified URI or HTTP method, to a request header. For example, add Content-Type that defines a request body type to request for the authentication information.

Common request headers are as follows:

**Table 3** Common request headers
Parameter	Description	Mandatory	Example Value
Content-Type	Message body type (or format)	Yes	application/json
X-Auth-Token	User token. It is a response to the API for obtaining a user token (only this API does not require authentication).	This parameter is mandatory for token authentication.	-
x-sdk-date	Time to send a request The time is in YYYYMMDD'T'HHMMSS'Z' format. The value is the Greenwich Mean Time (GMT) of the current system.	This parameter is mandatory for AK/SK authentication.	20160629T101459Z
Authorization	Authentication information. The value is obtained from the request signing result.	This parameter is mandatory for AK/SK authentication.	-
Host	Server information, which is obtained from the URL of a service API. This value is host name[:port number]. If the port number is not specified, the default port is used. The default port number for https is 443.	This parameter is mandatory for AK/SK authentication.	-

NOTE:

In addition to supporting authentication using tokens, public cloud APIs support authentication using the AK/SK, which uses SDKs 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 information about authentication using the AK/SK, see the API Signing Guide.

The API for obtaining a user token does not require authentication. Therefore, this API only requires adding the Content-Type field. The request with the added Content-Type header is as follows:

POST https://iam.ap-southeast-1.myhuaweicloud.com/v3/auth/tokens
Content-Type: application/json

Request Body

A request body is generally sent in structured format. It corresponds to Content-Type in the request header and transfers data except the request header. If the request body contains Chinese characters, these characters must be encoded in UTF-8.

The request body varies according to APIs. Certain APIs do not require the request body, such as the GET and DELETE APIs.

For the API of obtaining a user token, obtain the request parameters and parameter description in the API request. The following provides an example request with a body included. Replace username, domainname, ******** (login password), and xxxxxxxx (project name) with the actual values. To learn how to obtain your username, account name, and project ID, see Obtaining the Username, User ID, Project Name, and Project ID.

NOTE:

scope specifies where a token takes effect. In the following example, the token takes effect only on the resources specified by the project ID. You can set scope to an account or a project under an account. For details, see Obtaining a User Token..

 
POST https://iam.ap-southeast-1.myhuaweicloud.com/v3/auth/tokens
Content-Type: application/json 

{ 
    "auth": { 
        "identity": { 
            "methods": [ 
                "password" 
            ], 
            "password": { 
                "user": { 
                    "name": "username",       //Replace the value with the actual username.
                    "password": "********",   //Replace the value with the actual password.
                    "domain": { 
                        "name": "domainname"  //Replace the value with the actual domain name.
                    } 
                } 
            } 
        }, 
        "scope": { 
            "project": { 
                "name": "xxxxxxxxxx" //Replace the value with the actual project name.
            } 
        } 
    } 
}

If all data required by a request is available, you can send the request to call an API through curl, Postman, or coding. For the API of obtaining a user token, x-subject-token in the response header is the desired user token. Then, you can use the token to authenticate the calling of other APIs.

Parent topic: Calling APIs

Previous topic: Calling APIs

Next topic: Authentication