Making an API Request
This section describes the structure of a REST API and how to call an API. Before calling an API, you need to . The obtained token can then be used to authenticate the calling of 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 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 | Domain name or IP address of the server bearing the REST service. The endpoint varies between services in different regions. It can be obtained from . |
| 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 used to obtain 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 a maximum of 10 data records will be displayed. |
To simplify the URI display, each API is provided only with 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
| Method | Description |
|---|---|
| GET | Requests the server to return the 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. |
For example, in the case of the API used to , the request method is POST. The request is as follows:
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 the authentication information.
| Name | Description | Mandatory | Example Value |
|---|---|---|---|
| Host | 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 | code.test.com or code.test.com:443 |
| Content-Type | 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 | Length of the request body. The unit is byte. | No | 3495 |
| X-Project-Id | Project ID. Obtain the project ID by following the instructions in Obtaining a Project ID. | No | e9993fc787d94b6c886cbaa340f9c0f4 |
The API used to does not require authentication. Therefore, only the Content-Type field needs to be added to requests for calling the API. An example of such requests is as follows.
(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.
scope specifies where a token takes effect. In the example, the token takes effect only on the resources specified by the project ID. 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 more information about this API, see .
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 the request to call the 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. This token can then be used to authenticate the calling of other APIs.
