Making an API Request

Scenario

This section describes the structure of a REST API request, and uses the API for creating an IAM user as the administrator as an example to demonstrate how to call an API.

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 transmitted separately.

For example, if you want to create an IAM user, use the endpoint of any region (such as iam.ap-southeast-1.myhuaweicloud.com of CN-Hong Kong) because IAM is a global service. You can find the resource-path (/v3.0/OS-USER/users) in the URI of the API for creating an IAM user as the administrator. Then, construct the URI as follows:

1

https://iam.ap-southeast-1.myhuaweicloud.com/v3.0/OS-USER/users

Figure 1 Example URI

To simplify the URI display, each API is provided only 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 Method

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

Request Header

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

Common request header fields are as follows:

In addition to 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 information) and X-Sdk-Date (time when the request is sent) header fields are automatically added to the request.

For more information, see "AK/SK-based Authentication" in Authentication.

For the API used to create an IAM user as the administrator, if AK/SK authentication is enabled, the request with the header is as follows:

POST https://iam.ap-southeast-1.myhuaweicloud.com/v3.0/OS-USER/users
Content-Type: application/json
X-Sdk-Date: 20240416T095341Z 
Authorization: SDK-HMAC-SHA256 Access=****************, SignedHeaders=content-type;host;x-sdk-date, Signature=****************

Request Body (Optional)

The body of a request is often sent in a structured format as specified in Content-Type. The request body transfers content except the request header. If the request body contains Chinese characters, set Content-type to utf-8, for example, Content-Type: application/json; charset=utf-8.

The request body varies depending on APIs. Some APIs do not require the request body, such as the APIs requested using the GET or DELETE method.

For the API used to create an IAM user as the administrator, the required parameter and description are in the request part of the API. An example of such requests is as follows. Use actual values for the bold fields.

• accountid: account ID of the IAM user
• username: IAM username to be created
• email: email address of the IAM user
• **********: password of the IAM user

POST https://iam.ap-southeast-1.myhuaweicloud.com/v3.0/OS-USER/users
Content-Type: application/json
X-Sdk-Date: 20240416T095341Z 
Authorization: SDK-HMAC-SHA256 Access=****************, SignedHeaders=content-type;host;x-sdk-date, Signature=**************** 
 
{ 
     "user": { 
         "domain_id": "accountid", 
         "name": "username", 
         "password": "**********", 
         "email": "email", 
         "description": "IAM User Description" 
     } 
 }

If all data required for the API request is available, you can send the request to call the API through curl, Postman, or coding.