Request URI

A request URI is in the following format:

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

Although a request URI is included in the request header, most programming languages and frameworks require separate transmission of the request URI.

• URI-scheme: protocol used to transmit requests. All APIs use HTTPS.
• Endpoint: domain name or IP address of the server bearing the REST service. The endpoint varies for services in different regions. It can be obtained from Regions and Endpoints. For example, the endpoint of RES in the CN North-Beijing1 region is res.cn-north-1.myhuaweicloud.com.
• resource-path: access path of an API for performing a specified operation. The path is obtained 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 the IAM token in region CN North-Beijing1, obtain the endpoint (iam.cn-north-1.myhuaweicloud.com) of this region and the resource-path (/v3/auth/tokens) in the URI of the API to obtain a user token. Then, construct the URI as follows:

https://iam.cn-north-1.myhuaweicloud.com/v3/auth/tokens

Figure 1 Example URI

To simplify URI display in this document, each API is only provided with a resource-path and a request method. The URI-scheme of all APIs is HTTPS, and the endpoints of all APIs in the same region are identical.

Request Methods

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

• GET requests the 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 specified resources, for example, an object.
• HEAD is the same as GET except the server must return only the response header.
• PATCH requests the server to update partial content of a specified resource. If the resource does not exist, a new resource will be created.

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.cn-north-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 HTTP method. For example, to request the authentication information, add Content-Type, which specifies the request body type.

Common request header fields are as follows:

• Content-Type specifies the request body type or format. This field is mandatory and its default value is application/json. Other values of this field will be provided for any specific APIs.
• X-Auth-Token specifies the user token, which is optional. This field is mandatory for token-based authentication. The user token is a response to the API used to obtain a user token. This API is the only one that does not require authentication.

In addition to supporting authentication using tokens, public cloud APIs support authentication using the access key ID (AK)/secret access key (SK), using SDKs to sign a request. During the signing, the Authorization (signature authentication information) and X-Sdk-Date (time when a request is sent) headers are automatically added to the request.

For more information, see AK/SK Authentication.

• X-Project-ID specifies a subproject ID. This parameter is mandatory only in multi-project scenarios.
• X-Domain-ID specifies an account ID.

The API used to obtain a user token does not require authentication. Therefore, this API only requires addition of the Content-Type field. An example of such a request is as follows:

POST https://iam.cn-north-1.myhuaweicloud.com/v3/auth/tokens 

Content-Type: application/json

Request Body

The body of a request is often sent in a structured format as specified in the Content-Type header field. The request body transfers content other than the request header. If the request body contains Chinese characters, these characters must be coded in UTF-8.

The request body varies between APIs. Some APIs do not require the request body, such as the APIs requested using the GET and DELETE methods.

In the case of the API used to obtain a user token, the request parameters and parameter description can be obtained from the API request. The following provides an example request with a body included. Replace username, domainname, ******** (login password), and xxxxxxxxxx (project name) with the actual values. To learn how to obtain your username, account name, and project name (for example, cn-north-1), see Obtaining Account, IAM User, and Project.

The scope parameter specifies where a token takes effect. In the following example, the token takes effect only for the resources in a specified project. For more information, see Obtaining a User Token.

POST https://iam.cn-north-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": "xxxxxxxx" 
            } 
        } 
    } 
}

If all data required for the API request is available, you can send the request to call the API through curl, Postman, or coding. In the response to the API used to obtain a user token, x-subject-token is the desired user token. This token can be used to authenticate the calling of other APIs.