Making an API Request

This section describes the structure of a REST API request, and uses the IAM API for obtaining a user token as an example to demonstrate how to call an API. The obtained 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 the request URI to be transmitted separately.

Table 1 URI parameter description
Parameter	Description
URI-scheme	Protocol used to transmit requests. All APIs use HTTPS.
Endpoint	The domain name or IP address providing REST services. Endpoints vary depending on service types and regions. You can obtain service endpoints from Regions and Endpoints. For example, IAM endpoint for the ru-moscow-1 region is iam.ru-moscow-1.hc.cloud.ru.
resource-path	Access path of an API for performing a specified operation. It can be obtained from the URI of an API. For example, the resource-path of the API used for obtaining a user token is /v3/auth/tokens.
query-string	(Optional) Query parameter. Not all APIs have a query parameter. A question mark (?) should be included before each query parameter. The format is Parameter name=Parameter value, such as, ? limit=10 (indicating that up to 10 data records will be displayed).

Note

API URIs are simplified to display only the resource-path together with the request method. The URI-scheme of all APIs is HTTPS, and the endpoints of all APIs in the same region are identical.

Request Methods

The HTTP protocol defines the following request methods:

Table 2 HTTP methods
Method	Description
GET	Requests that a server return specified resources.
PUT	Requests that a server update specified resources.
POST	Requests that a server add resources or perform special operations.
DELETE	Requests that a server delete specified resources, for example, an object.
HEAD	Same as GET except that the server only returns the response header.
PATCH	Requests that a server update part of a specified resource. If the resource does not exist, a new resource will be created.

For example, in the case of the API used to obtain a user token, the request method is POST. The request is as follows:

POST https://iam.ru-moscow-1.hc.cloud.ru/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, to request for the authentication information, add Content-Type, which specifies the request body type.

Table 3 lists common request header fields.

Table 3 Common request headers
Name	Description	Mandatory	Example
Host	Specifies the server domain name and port number of the resources being requested. The value can be obtained from the URL of the service API. The value is in the format of Hostname:Port number. If the port number is not specified, the default port is used. The default port number for HTTPS is 443.	No This field is mandatory for AK/SK authentication.	code.test.com or code.test.com:443
Content-Type	Specifies the request body MIME type. 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	Specifies the length of the request body. The unit is byte.	No	3495
X-Project-Id	Specifies the project ID. Obtain the project ID by following the instructions in Obtaining a Project ID.	No This field is mandatory for requests that use AK/SK authentication in the DeC scenario or multi-project scenario.	e9993fc787d94b6c886cbaa340f9c0f4
X-Auth-Token	Specifies the user token. Obtain the token by calling the API for obtaining a user token (only this API does not require authentication). After the request is processed, the value of X-Subject-Token in the header is the token value.	No This field is mandatory for token authentication.	The following is part of an example token: MIIPAgYJKoZIhvcNAQcCo...ggg1BBIINPXsidG9rZ

Note

In addition to supporting authentication using tokens, 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.

POST https://iam.ru-moscow-1.hc.cloud.ru/v3/auth/tokens
Content-Type: application/json

(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.

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 example, in the case of the API used to obtain user tokens, the request parameters and parameter description can be obtained from the API request. The following provides an example request. Bold italic fields need to be replaced with actual values. username indicates the user name. domainname indicates the account name. $ADMIN_PASS indicates the password. xxxxxxxxxxxxxxxxxx indicates the project name. You can obtain API endpoints from Regions and Endpoints.

Note

The scope parameter defines a scope where a token applies. The token in the example here can only give you access to resources in the specified project. You can set the applicable scope of a token to be all resources from a certain account or resources from a specific project in an account. For more details, see "Obtaining a User Token".

POST https://iam.ru-moscow-1.hc.cloud.ru/v3/auth/tokens 
Content-Type: application/json

{
    "auth": {
        "identity": {
            "methods": [
                "password"
            ],
            "password": {
                "user": {
                    "name": "username",
                    "password": "$ADMIN_PASS",     //You are advised to store it in ciphertext in the configuration file or an environment variable and decrypt it when needed to ensure security.
                    "domain": {
                        "name": "domainname"
                    }
                }
            }
        },
        "scope": {
            "project": {
                "name": "xxxxxxxxxxxxxxxxxx"
            }
        }
    }
}

Now you have constructed a complete API request, and you can send this request by using curl or Postman or writing code. 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

Была ли эта статья полезна?

Поддержка Юридические документы