This section describes the structure of a REST API request, and uses the 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}
+ +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. It can be obtained in Endpoint. + |
+
resource-path + |
+Access path of an API. 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 + |
+(Optional) Query parameter. Put a question mark (?) at the beginning. The format is 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. All API URI schemes are HTTPS and the endpoints are the same in the same region.
+Request Method
HTTP defines the following request modes that can be used to send a request to the server:
+ +Method + |
+Description + |
+
|---|---|
GET + |
+Request the server to return a specific resource. + |
+
PUT + |
+Request the server to update a specific resource. + |
+
POST + |
+Request the server to create a new resource or perform a special operation. + |
+
DELETE + |
+Request the server to delete a specific resource, such as an object. + |
+
HEAD + |
+Request the server for the resource headers. + |
+
PATCH + |
+Request the server to update a portion of the resource content. +PATCH may create a new resource if it does not exist. + |
+
For example, if you use the POST method to obtain the URI of a user token, the request is as follows:
+POST https://{iam-endpoint}/v3/auth/tokens
+Request Header
You can add additional fields, for example, the fields required by a specified URI or HTTP method, to a request header. For example, add Content-Type, which specifies the request body type, to a request for the authentication information.
+Table 3 describes the common request header fields to be added to the request.
+ +Header + |
+Description + |
+Mandatory + |
+Example + |
+
|---|---|---|---|
Content-type + |
+Message body type (format). The default value is application/json. + |
+Yes + |
+application/json + |
+
X-Auth-Token + |
+User token +Response for calling the Obtaining a User Token API. This API is the only one that does not require authentication. After the request is processed, the value of X-Subject-Token in the response header (Header) is the token value. + |
+Mandatory for token-based authentication + |
+MIIPAgYJKoZIhvcNAQcCo...ggg1BBIINPXsidG9rZ + |
+
The API used to obtain a user token 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:
+POST https://{iam-endpoint}/v3/auth/tokens
+Content-Type: application/json
+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.
+For an API, the request parameters and parameter description are available in the request. The following provides an example request with a body included. Replace user_name, domain_name, ******** (login password), and xxxxxxxx (project ID) with the actual values. To learn how to obtain a project ID, see Obtaining the Project ID.
+ The scope parameter specifies where a token takes effect. In the example, the token takes effect only for the resources in a specified project. OCR uses a region-specific endpoint to call this API. Set scope to project. You can set scope to an account or a project under an account.
+POST https://{iam-endpoint}/v3/auth/tokens
+Content-Type:application/json
+{
+ "auth": {
+ "identity": {
+ "methods": ["password"],
+ "password": {
+ "user": {
+ "name": "user_name",
+ "password": "********",
+ "domain": {
+ "name": "domain_name"
+ }
+ }
+ }
+ },
+ "scope": {
+ "project": {
+ "name": "xxxxxxxx"
+ }
+ }
+ }
+}
+If all data required for the API request is available, you can send the request to call the API through curl, Postman, or coding. 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.
+
