Making an API Request

This section describes the structure of a REST API request, and calls the IAM API for obtaining a user token as an example. The obtained token can then be used to authenticate the calling of other APIs.

Request URI

The format of a request URI is as follows:

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

**Table 1** Request URI
Parameter	Description
URI-scheme	Protocol used to transmit requests. All APIs use HTTPS.
Endpoint	Domain name or IP address of the server for the REST service endpoint. The endpoint varies depending on services in different regions. Obtain the value from Endpoints. For example, the endpoint of VIAS in region CN North-Beijing1 is iam.cn-north-1.myhuaweicloud.com.
resource-path	Access path of an API for performing a specified operation. Obtain the path from the URI of an 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 a 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.

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

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

**Table 2** HTTP methods
Method	Description
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	Requests a server for the resource header.
PATCH	Requests the server to update partial content of a specified resource. If the resource is unavailable, the PATCH method is used to create a resource.

For example, in the URI for obtaining a user token, the request method is POST, and 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 an HTTP method. For example, add Content-Type that defines a request body type to request for the authentication information.

Table 3 describes the common request header fields to be added to the request.

**Table 3** Common request header fields
Parameter	Description	Mandatory	Example
Content-type	Request body type or format. Its default value is application/json.	Yes	application/json
Content-Length	Length of the request body, in bytes.	This parameter is mandatory for POST and PUT requests, but must be left blank for GET requests.	3495
X-Project-Id	Project ID. This parameter is used to obtain the token for each project.	No	e9993fc787d94b6c886cbaa340f9c0f4
X-Auth-Token	User token, which is a response to the API for obtaining a user token (only this API does not require authentication).	No This parameter is mandatory for token-based authentication.	N/A
X-Sdk-Date	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.	No Mandatory for AK/SK-based authentication, but not required for PKI token-based authentication	20190307T101459Z
Authorization	Signature authentication information. The value is obtained from the request signature result and is required when the AK and SK are used to encrypt the signature. Type: string Default value: none	No Mandatory for AK/SK-based authentication	SDK-HMAC-SHA256 Credential=ZIRRKMTWPTQFQI1WKNKB/20150907//ec2/sdk_request, SignedHeaders=content-type;host;x-sdk-date, Signature=55741b610f3c9fa3ae40b5a8021ebf7ebc2a28a603fc62d25cb3bfe6608e1994
Host	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 443.	No Mandatory for AK/SK-based authentication	code.test.com or code.test.com:443

In addition to supporting authentication using tokens, public cloud APIs support authentication using AK/SK, which uses SDKs to sign a request. During the signature, the Authorization (signature authentication) and X-Sdk-Date (time when a request is sent) headers are automatically added in the request. For more information about AK/SK-based authentication, see AK/SK Signing and Authentication Guide.

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.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 Content-Type. The request body transfers content other than the request header. If the request body contains Chinese characters, these characters must be encoded 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, and ******** with the actual username, account name, and login password, respectively. cn-north-1 is the project name. For details, see Obtaining Account, IAM User, and Project Information.

scope specifies where a token takes effect. Its value can be project or domain. In the preceding example, the value of scope is project, indicating that the token can access only resources of the specified project. If the value of scope is domainname, the token can access all resources of the specified account. For details, 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", //Replace it with the actual username.
          "password": "**********",//Replace it with the actual password.
          "domain": {
            "name": "domianname"  //Replace it with the actual account name.
          }
        }
      }
    },
    "scope": {
      "project": {
        "name": "cn-north-1"  //Replace it with the actual project name to obtain the token of the specified project.
      }
    }
  }
}

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

In the response to the API used to obtain a user token, x-subject-token is the desired user token. This token can then be used to authenticate the calling of other APIs.

Parent topic: Calling APIs

Previous topic: Calling APIs

Next topic: Authentication