Making an API Request

This section describes the structure of a REST API request, and uses the IAM service as an example to explain how to obtain a user token to call an API. The obtained token can then be 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** Parameters in a URI
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. Endpoints vary depending on services and regions. For the endpoints of all services, see Regions and Endpoints. For example, the endpoint of IAM in region CN-Hong Kong is iam.ap-southeast-1.myhuaweicloud.com.
resource-path	Access path of an API for performing a specified operation. Obtain the value from the URI of an API. For example, the resource-path of the API used to obtain a user token is /v3/auth/tokens.
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 an IAM token in the CN-Hong Kong region, obtain the endpoint of IAM (iam.ap-southeast-1.myhuaweicloud.com) for this region and the resource-path (/v3/auth/tokens) in the URI of the API used to obtain a user token. Then, construct the URI as follows:

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

Figure 1 Example URI

To simplify the URI display, each API is provided with only a resource-path and a 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 Methods

HTTP-based request methods, which are also called operations or actions, specify the type of operations that you are requesting.

**Table 2** HTTP method
Request Method	Description
GET	Requests a server to return specified resources.
PUT	Requests the server to update specified resources.
POST	Requests the server to add resources or perform special operations.
DELETE	Requests the server to delete a specific resource, for example, an object.
HEAD	Same as GET except that the server must return only the response header.
PATCH	Requests a server to update part of specified resources. If the resource is unavailable, the PATCH method is used to create a resource.

For example, in the case of the API used to obtain a user token, the request method is POST. The request is as follows:

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

Request Header

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

Table 3 lists common request header fields.

**Table 3** Common request headers
Parameter	Description	Mandatory	Example
Host	Specifies the information about the requested server. The value can be obtained from the URL of the service API. The value is hostname[:port]. If the port number is not specified, the default port is used. The default port number for https is port 443.	No This header field is mandatory if AK/SK authentication is in use.	code.test.com or code.test.com:443
Content-Type	Specifies the request body type or format. This field is mandatory and its default value is application/json. For other values, the description will be provided for specific APIs.	Yes	application/json
Content-Length	Indicates the length of the request body. The unit is byte.	This field is mandatory for POST and PUT requests, but must be left blank for GET requests.	3495
X-Project-ID	Project ID. It is mandatory in multi-project scenarios to obtain tokens for different projects.	No	e9993fc787d94b6c886cbaa340f9c0f4
X-Auth-Token	User token. User token is a response to the API for obtaining a user token (only this API does not require authentication).	This parameter is mandatory only for authentication using tokens.	The following is part of an example token: MIIPAgYJKoZIhvcNAQcCo...ggg1BBIINPXsidG9rZ
Authorization	Specifies the signature authentication information. The value can be obtained from the request signing result.	This header field is mandatory if AK/SK authentication is in use.	-
X-Sdk-Date	Specifies the time when the request is sent. The time is in YYYYMMDD'T'HHMMSS'Z' format. The value is the current Greenwich Mean Time (GMT) of the system.	This header field is mandatory if AK/SK authentication is in use.	20150907T101459Z
X-Language	Request language.	No	en-us

In addition to supporting token-based authentication, APIs also support authentication using access key ID/secret access key (AK/SK). During AK/SK-based authentication, an SDK is used to sign the request, and the Authorization (signature authentication) and X-Sdk-Date (time when the request is sent) header fields are automatically added to the request.

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 a structured format. It corresponds to Content-Type in the request header and transfers data except for the request header.

The request body varies according to the 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 from the API request. The following provides an example request with a body included. Replace username, domainname, ******** (login password), and xxxxxxxxxxxxxxxxxx (project ID) with the actual values. Obtain a project ID from Regions and Endpoints.

scope specifies where a token takes effect. In the following example, the token takes effect only on the resources specified by the project ID. In the following example, the token takes effect only for the resources in a specified project. For more information about this API, 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",
                    "password": "********",
                    "domain": {
                        "name": "domainname"
                    }
                }
            }
        },
        "scope": {
            "project": {
                "name": "xxxxxxxxxxxxxxxxxx"
            }
        }
    }
}

        

      

    
   

If all data required by a request is available, you can send the request to call an API through curl, Postman, or coding. In the response to the IAM API used to obtain a user token, x-subject-token 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