Making an API Request

Updated on 2025-03-21 GMT+08:00

View PDF

This section describes the structure of a REST API request, and uses the API for obtaining a user access token in OAuth 2.0 client authentication mode as an example to demonstrate how to call an API. The obtained access token can then be 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 the request header, most programming languages or frameworks require passing the request URI separately.

**Table 1** URI parameters
Parameter	Description
URI-scheme	Protocol used to transmit requests. All APIs use HTTPS.
Endpoint	Domain name or IP address of the Huawei Cloud Astro Zero server bearing the REST service.
resource-path	Access path of an API for performing the specified operation. Obtain the path from the URI of an API. For example, the resource-path of the API used to obtain a user token is /baas/auth/v1.0/oauth2/token.
query-string	(Optional) Query parameter. Ensure that a question mark (?) is included before each query parameter. For example, ? limit=10 indicates that a maximum of 10 data records will be displayed. Separate multiple query parameters with ampersands (&).

For example, to obtain the user access token using OAuth 2.0 client credentials, obtain the resource path /baas/auth/v1.0/oauth2/token, assume that the domain name of Huawei Cloud Astro Zero in the development state is appcube.cn-north-4.huaweicloud.com, and construct the URI as follows:

https://appcube.cn-north-4.huaweicloud.com/baas/auth/v1.0/oauth2/token

Request Methods

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

**Table 2** HTTP-based methods
Method	Description
GET	Requests the server to return specified resources, for example, to return an object list.
PUT	Requests the server to update a specified resource, for example, update data by record ID.
POST	Requests the server to add resources or perform special operations, such as adding object data.
DELETE	Requests the server to delete a specified resource, for example, delete object data by record ID.
HEAD	Requests the server to return the response header.
PATCH	Requests the server to update partial contents of a specified resource. If the resource was not found, a new resource will be created.

For example, in the case of the API used to obtain a user access token by using OAuth 2.0 client credentials, the request method is POST. The request is as follows:

POST https://appcube.cn-north-4.huaweicloud.com/baas/auth/v1.0/oauth2/token

Request Header

Request headers include those required by a specific URI or HTTP method, such as Content-Type, which defines the data type, or the authentication header.

Table 3 describes common request headers.

**Table 3** Common request headers
Header	Description	Mandatory
Content-Type	Parameter defined in the HTTP protocol, which identifies the format for parsing the returned content. If the value is application/json, the browser parses the returned content into a JSON object. If the value is application/x-www-form-urlencoded, the browser parses the returned content into URL-encoded format.	Yes
tenant-id	Account ID, which is unique and identifies the account who receives the request.	No
access-token	Access token required for calling the Huawei Cloud Astro Zero APIs. Include this token in the request header when making the API call to authenticate and gain permission to operate the API. When a user or portal user logs in to the platform with an account and password, the backend generates an access token. This token is then included in the response message and stored in the browser. When the user/portal user sends a request to Astro Zero, the token will be carried, indicating that the user/portal has been authenticated. When a third-party system accesses Huawei Cloud Astro Zero APIs, it must first be authenticated using the OAuth protocol to obtain a client ID and client secret. Then, use these credentials to call the API via /baas/auth/v1.0/oauth2/token to obtain an access token, which grants access to Huawei Cloud Astro Zero's APIs.	No Mandatory for access-token authentication.

If OAuth 2.0 client credentials are used, the API for obtaining a user's access_token does not require access-token authentication. Therefore, only the Content-Type field whose value is application/x-www-form-urlencoded needs to be added to requests for calling the API. An example of such requests is as follows:

POST https://appcube.cn-north-4.huaweicloud.com/baas/auth/v1.0/oauth2/token
Content-Type: application/x-www-form-urlencoded

(Optional) Request Body

The body of a request is often sent in a structured format (JSON or XML) as specified in the Content-type header field. The request body transfers content except the request header. Chinese characters in a request body must be UTF-8 encoded.

Request bodies vary with APIs. Some APIs do not require a request body, such as the APIs requested using the GET and DELETE methods.

For the request parameters of the API used to obtain a user access token using OAuth 2.0 client credentials, see Table 4.

**Table 4** Request parameters
Name	Type	Mandatory (M)/Optional (O)	Location	Description
grant_type	String	M	Body	Authorization mode, which is the value of grant_type in OAuth 2.0. Example: client_credentials (client mode)
client_id	String	M	Body	Client ID. To obtain the client ID, perform the following steps: On the Huawei Cloud Astro Zero console, click Access Homepage. The application development page is displayed. In the upper left corner of the page, click and choose Environments > Environment Configuration. Choose Integrated connection > OAuth and click New. Enter a name, set the authorization type to client mode, and select a user. After the authentication is successful, the user obtains the same permissions as the user. Do not select users with Anonymous_User_Profile permission because they cannot access APIs. In the OAuth Manager list, click in the row where the OAuth is located to download the key file to the local host and obtain the value of client_id.
client_secret	String	M	Body	Client secret. Refer to the operations for obtaining the client_id to get the client_secret value.
redirect_url	String	O	Body	Redirection URL.
locale	String	O	Body	Language. Example: en_US

The following provides an example request with a body included. Replace the italic fields in bold with the actual values.

POST https://appcube.cn-north-4.huaweicloud.com/baas/auth/v1.0/oauth2/token
Content-Type: application/x-www-form-urlencoded 
  
grant_type=client_credentials&client_id=********&client_secret=********

Initiating a Request

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

For the response of the API used to obtain a user access token using OAuth 2.0 client credentials, access_token is the user access token which can be used to call other Huawei Cloud Astro Zero APIs.

Parent topic: Calling APIs

Previous topic: Calling APIs

Next topic: Authentication