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 other APIs.
Request URI
A request URI consists of the following:
{URI-scheme}://{Endpoint}/{resource-path}?{query-string}
Although a request URI is included in the request header, most programming languages or frameworks require the request URI to be separately transmitted, rather than being conveyed in a request message separately.
| Parameter | Description |
|---|---|
| URI-scheme | Protocol used to transmit requests. All APIs use HTTPS. |
| Endpoint | Domain name or IP address of a server where a REST service endpoint is hosted. The endpoint varies depending on services and regions. It can be obtained from the administrator. For example, the endpoint of IAM in the EU-Dublin region is iam.eu-west-101.myhuaweicloud.eu. |
| resource-path | Access path of an API for performing a specified operation. Obtain the path 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. 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 up to 10 data records will be displayed. |
Request Methods
| Method | Description |
|---|---|
| GET | Requests a server to return specified resources. |
| PUT | Requests a server to update specified resources. |
| POST | Requests a server to add a resource or perform a special operation. |
| DELETE | Requests a server to delete a specified resource (for example, an object). |
For example, in the URI for obtaining a user token, the request method is POST. The request is as follows:
POST https://iam.eu-west-101.myhuaweicloud.eu/v3/auth/tokens
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, add Content-Type that defines a request body type to request for authentication information.
| Parameter | Description | Mandatory | Example Value |
|---|---|---|---|
| Content-Type | MIME type of the request body. Use the default value application/json. For APIs used to upload objects or images, the value varies depending on the flow type. | This field is optional for GET requests and mandatory for other requests. | application/json |
| Content-Length | Length of the request body. The unit is byte. | This field is optional for POST requests, but must be left blank for GET requests. | 3495 |
| X-Project-Id | Project ID. To obtain the project ID, see Obtaining a Project ID. | No | e9993fc787d94b6c886cbaa340f9c0f4 |
| X-Auth-Token | User token. After a request is processed, the value of X-Subject-Token in the header is the token value. | Yes | The following is part of an example token: MIIPAgYJKoZIhvcNAQcCo...ggg1BBIINPXsidG9rZ |
The API used to obtain a user token does not require authentication. Therefore, this API only requires adding the Content-Type field. The following is an example request:
POST https://iam.eu-west-101.myhuaweicloud.eu/v3/auth/tokens Content-Type: application/json
(Optional) Request Body
This part is optional. The request body is often sent in a structured format (for example, JSON or XML) as specified in the Content-Type header field. If the request body contains full-width characters, these characters must be coded in UTF-8.
Request bodies vary depending on APIs. Some APIs do not require a request body, such as the APIs requested using the GET and DELETE methods.
For the API of obtaining a user token, request parameters and parameter description can be obtained from the API request. The following is an example request with a body included. Replace username, domainname, ******** (login password), and xxxxxxxxxxxxxxxxxx (project name) with required values. You can obtain the values from the administrator.
The scope parameter specifies where a token takes effect. You can set scope to an account or a project under an account. In the following example, the token takes effect only for the resources in a specified project. For details, see Obtaining a User Token.
POST https://iam.eu-west-101.myhuaweicloud.eu/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 for the API request is available, you can send a 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 required user token. Then, this token can be used to authenticate the calling of other APIs.
