Making an API Request
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.
| 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. Obtain the value from Regions and Endpoints. |
| resource-path | API access path for performing a specified operation. 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 | Query parameter, which is optional. 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. |
To simplify 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
| Method | Description |
|---|---|
| GET | Requests a server to return the specified resources. |
| PUT | Requests a server to update specified resources. |
| POST | Requests a server to add resources or perform special operations. |
| DELETE | Requests a server to delete specified resources, for example, an object. |
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 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.
| Name | Description | Mandatory | Example |
|---|---|---|---|
| Host | Specifies the requested server information, which can be obtained from the URL of the service API. The value is in the hostname[:port] format. If the port number is not specified, the default port is used. The default port number for https is 443. | No This parameter is mandatory for AK/SK authentication. | code.test.com or code.test.com:443 |
| Content-Type | Specifies the MIME type of the request body. You are advised to use the default value application/json. For APIs used to upload objects or images, the value can vary depending on the flow type. | Yes | application/json |
| Content-Length | Specifies the length of the request body. The unit is byte. | This parameter is optional for POST requests, but must be left blank for GET requests. | 3495 |
| X-Project-Id | Specifies the project ID. Obtain the project ID by following the instructions in Obtaining a Project ID. | No This parameter is mandatory for requests that use AK/SK authentication in the Dedicated Cloud (DeC) scenario or multi-project scenario. | e9993fc787d94b6c886cbaa340f9c0f4 |
| X-Auth-Token | Specifies the user token. After the request is processed, the value of X-Subject-Token in the header is the token value. | No This parameter is mandatory for token authentication. | The following is part of an example token: MIIPAgYJKoZIhvcNAQcCo...ggg1BBIINPXsidG9rZ |
In addition to supporting token-based authentication, APIs 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.
The API used to obtain 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
(Optional) Request Body
This part is optional. A request body is generally sent in a structured format (for example, JSON or XML), corresponding to Content-Type in the request header, and is used to transfer content other than the request header. If the request body contains full-width characters, these characters must be coded in UTF-8.
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 used to , the request parameters and parameter description can be obtained in the API request. The following provides an example request with a body included. Replace username, domianname, ******** (login password), and xxxxxxxxxxxxxxxxxx (project ID, for example, ap-southeast-1) with the actual values. Obtain the value from the 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. You can set the 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",
"password": "********",
"domain": {
"name": "domianname"
}
}
}
},
"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. For the API used to obtain 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.
