Making an API Request
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.
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.
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.
Header |
Description |
Mandatory |
---|---|---|
Content-Type |
Parameter defined in the HTTP protocol, which identifies the format for parsing the returned content.
|
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.
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. Options:
|
client_id |
String |
M |
Body |
Client ID. To obtain the client ID, perform the following steps:
|
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.
Feedback
Was this page helpful?
Provide feedbackThank you very much for your feedback. We will continue working to improve the documentation.See the reply and handling status in My Cloud VOC.
For any further questions, feel free to contact us through the chatbot.
Chatbot