API requests sent by third-party applications to public cloud services must be authenticated using signatures.
+
This document describes the signature procedure, provides sample code to illustrate how to use the default signer to sign requests and how to use the HTTP client to send requests.
+
API Gateway provides RESTful APIs.
+
REST provides APIs to create, query, update, delete, and access service resources.
+
A REST API request/response pair is divided into the following parts:
+
- Request URI
- Request method
- Request headers
- Request body
- Response headers
- Response body
+
Request URI
A request URI consists of the following parts:
+
{URI-scheme} :// {Endpoint} / {resource-path} ? {query-string}
+
Although a request URI is a part of a request header, most programming languages or frameworks require the request URI to be separately transmitted, rather than being conveyed in a request message.
+
+
Table 1 URI parameter descriptionParameter
+ |
+Description
+ |
+
|---|
+
+URI-scheme
+ |
+Protocol used to transmit the request.
+ |
+
+Endpoint
+ |
+Domain name or IP address of the server where the RESTful service endpoint is hosted. You can obtain the value from Regions and Endpoints.
+ |
+
+resource-path
+ |
+Path in which the resource requested by the API is located. The path is provided by the URI module of APIs, for example, v3/auth/tokens.
+ |
+
+Query string
+ |
+This is an optional parameter. For example, the value can be the API version or resource selection criteria.
+ |
+
+
+
+
+
+
Request Method
HTTP method: the type of requested operation.
+
+
Table 2 HTTP methods supportedMethod
+ |
+Description
+ |
+
|---|
+
+GET
+ |
+Requests a server to provide a specified resource.
+ |
+
+PUT
+ |
+Requests a server to update a specified resource.
+ |
+
+POST
+ |
+Requests a server to add resources or perform special operations.
+ |
+
+DELETE
+ |
+Requests a server to delete a specified resource, for example, an object.
+ |
+
+HEAD
+ |
+Similar to the GET method, the HEAD method requests a server to provide the specified resource, but the server returns only the response header (excluding the response body) to this request.
+ |
+
+PATCH
+ |
+Requests a server to update a part of a specified resource.
+If the resource does not exist, the PATCH method may create a new resource.
+ |
+
+
+
+
+
+
Request Headers
Optional header fields: For example, such fields could be those required by a specified URI and HTTP method. Table 3 describes common HTTP request header fields.
+
+
Table 3 Common request headersHeader
+ |
+Description
+ |
+Remarks
+ |
+Example
+ |
+
|---|
+
+Content-Type
+ |
+Type (or format) of the message body.
+ |
+Mandatory
+ |
+application/json
+ |
+
+X-Auth-Token
+ |
+Token authentication information, which can be obtained by following the procedure in Token Authentication.
+ |
+Mandatory if token authentication is used.
+ |
+-
+ |
+
+X-Sdk-Date
+ |
+Time at which the request was sent.
+ |
+Mandatory if AK/SK authentication is used.
+ |
+20151222T034042Z
+ |
+
+Authorization
+ |
+Signature authentication information, which comes from the request signature result.
+ |
+Mandatory if AK/SK authentication is used.
+ |
+-
+
+ |
+
+
+
+
+
+
Request Body (Optional)
A request body conveys information other than the request header and is generally sent in a structured format (for example, JSON or XML) defined by the Content-type field.
+
+
Response Headers
A response header consists of an HTTP status code and additional response header fields.
+
- HTTP status code: A status code consists of three digits (2xx to 5xx). 2xx indicates a success response. 4xx and 5xx indicate an error response. The status code returned can also be defined by the service.
- Optional header fields: For example, Content-type could be one of such fields. Table 4 describes common response header fields.
+
Table 4 Response headersHeader
+ |
+Description
+ |
+Example
+ |
+
|---|
+
+Date
+ |
+A standard HTTP header, which indicates the date and time when a message is sent. The format of this header field is defined in RFC 822.
+ |
+Mon, 12 Nov 2007 15:55:01 GMT
+ |
+
+Server
+ |
+A standard HTTP header, which contains the information about the software that the server uses to process requests.
+ |
+Apache
+ |
+
+Content-Length
+ |
+A standard HTTP header, which indicates the size of the response body, in decimal number of bytes.
+ |
+xxx
+ |
+
+Content-Type
+ |
+A standard HTTP header, which specifies the media type of the response body sent to the recipient.
+ |
+application/json
+ |
+
+
+
+
+
+
Response Body (Optional)
A response body conveys information other than the response header and is generally sent in a structured format (for example, JSON or XML) defined by the Content-type field.
+
+
Initiating Requests
A request can be initiated by using any of the following methods:
+
- cURL
cURL is a command line tool used to perform URL operations and transmit information. It serves as an HTTP client to send HTTP requests to the server and receive response messages. cURL is suitable for use in API tuning scenarios. For more information about cURL, visit https://curl.haxx.se/.
+ - Code
You can call APIs through code to assemble, send, and process requests.
+ - REST client
Mozilla Firefox and Google Chrome provide a graphical browser plug-in for REST clients to send and process requests. For Mozilla Firefox, see REST Client APIsHub. For Google Chrome, see Postman.
+
+
+
Application Scenarios
If API requests are authenticated using tokens, the request header must contain X-Auth-Token (token information).
+
This section describes how to call an API for token authentication.
+
+
Procedure
- Send POST https://IAM endpoint/v3/auth/tokens to obtain the IAM endpoint and the region name in the message body.
See Regions and Endpoints.
+
+A cloud service can be deployed globally or at the project level.
+- A project-level service requires a project-level token. When you call the API, set auth.scope in the request body to project. The following services are at the project level: AOM, APIG, AS, BMS, CBR, CCE, Cloud Eye, CSBS, CSS, CTS, DataArts Studio, DC, DCS, DDS, Dedicated WAF, DeH, DIS, DLI, DMS, DNS, DRS, DWS, ECS, EIP, ELB, EVS, GaussDB (for MySQL), GaussDB NoSQL, IMS, KMS, LTS, ModelArts, MRS, NAT, PLAS, RDS, RTS, SDRS, SFS, SMN, SWR, VBS, VPC, VPCEP, VPN, and WAF.
- A global service requires a global token. When you call the API, set auth.scope in the request body to domain. The following services are global ones: Anti-DDoS, IAM, OBS, TMS, and TMS.
+The following shows an example of a project-level service request:
Replace the texts in italic with actual ones. For details, see Identity and Access Management API Reference.
+
Log in to the management console, click your username in the upper right corner, and choose My Credential from the drop-down list. On the My Credentials page, obtain your username, domain name, and project ID.
+
+
{
+ "auth": {
+ "identity": {
+ "methods": [
+ "password"
+ ],
+ "password": {
+ "user": {
+ "name": "username", // IAM username
+ "password": "password", // IAM user password
+ "domain": {
+ "name": "domainname" // Name of the domain to which the IAM user belongs
+ }
+ }
+ }
+ },
+ "scope": {
+ "project": {
+ "id": "0215ef11e49d4743be23dd97a1561e91" // Project ID
+ }
+ }
+ }
+}
+
The following shows an example of a global service request:
+{
+ "auth": {
+ "identity": {
+ "methods": [
+ "password"
+ ],
+ "password": {
+ "user": {
+ "name": "username", // IAM username
+ "password": "password", // IAM user password
+ "domain": {
+ "name": "domainname" // Name of the domain to which the IAM user belongs
+ }
+ }
+ }
+ },
+ "scope": {
+ "domain": {
+ "name": "domainname" // Name of the domain to which the IAM user belongs
+ }
+ }
+ }
+}
+ - Obtain the token. For details, see section "Obtaining the User Token" in the Identity and Access Management API Reference. If the request is successful, the value of the X-Subject-Token header in the response is the token.
The following figures illustrate how to use Postman to manually obtain a token.
+Figure 1 Example request
+Figure 2 Obtain X-Subject-Token from the header of the response message.
+ - Call a service API, add the X-Auth-Token header with the token obtained in 2.
+
+
When you use API Gateway to send requests to underlying services, the requests must be signed using the AK and SK.
+
AK is a unique identifier that is associated with a secret access key; the access key ID and secret access key are used together to sign requests cryptographically.
+
SK is a key that is used in conjunction with an access key ID to cryptographically sign requests. Signing a request identifies the sender and prevents the request from being altered.
+
+
The AK/SK authentication process is as follows:
+
- A standard request is created.
- A to-be-signed string is created using the request and other related information.
- A signature is calculated using the AK/SK and to-be-signed string.
- The generated signature is added as a header or a query parameter in the HTTP request.
- After receiving the request, API Gateway performs 1 to 3 to calculate a signature.
- The new signature is compared with the signature generated in 3. If they are consistent, the request is processed; otherwise, the request is rejected.
+
Figure 1 shows the process of calling APIs through AK/SK authentication.
+
Figure 1 API calling process flow
+
- If a failure occurs in any step, the failure will be returned to the client application.
- The cached token is valid for 15 minutes by default.
+
+
Scenario
This section describes how to call the API of a public cloud service by using Eclipse.
+
The following code shows how to sign a request and how to use an HTTP client to send an HTTPS request. The code is categorized into three classes:
- AccessService: an abstract class that merges the GET, POST, PUT, and DELETE methods into the access method.
- Demo: execution entry that simulates GET, POST, PUT, and DELETE requests.
- AccessServiceImpl: implementation of the access method. The code required for API Gateway communication is included in the access method.
+
+
You can download the sample code package from https://apig-demo.obs.eu-de.otc.t-systems.com/java/SdkDemo.zip.
+
The JDK version cannot be earlier than 1.8.
+
+
+
Procedure
- Download the sample code package and decompress it.
- Import the sample project to Eclipse.
Figure 1 Selecting an existing project
+Figure 2 Selecting the sample code file after decompression
+Figure 3 Structure of the project after importing
+ - Edit the main method in the Demo.java file.
Replace the bold texts with actual values. If you use other methods, such as POST, PUT, and DELETE, see the corresponding annotations.
+Replace the parameters in the URL, for example, project_id.
+For details on how to obtain your region name, service name, AK/SK, project ID, and domain ID, see Obtaining Required Information.
+//TODO: Replace eu-de with the name of the region in which the service to be accessed is located.
+private static final String region = "eu-de";
+
+//TODO: Replace vpc with the name of the service you want to access. For example, ecs, vpc, iam, and elb.
+private static final String serviceName = "vpc";
+
+public static void main(String[] args) throws UnsupportedEncodingException
+{
+//TODO: Replace the AK and SK with those obtained on the My Credential page.
+String ak = "ZIRRKMTWPTQFQI1WKNKB";
+String sk = "Us0mdMNHk******YrRCnW0ecfzl";
+
+//TODO: To specify a project ID (multi-project scenarios), add the X-Project-Id header.
+//TODO: To access a global service, such as IAM, DNS, CDN, and TMS, add the X-Domain-Id header to specify an account ID.
+//TODO: To add a header, find "Add special headers" in the AccessServiceImple.java file.
+
+//TODO: Test the API
+String url = "https://vpc.eu-de.otc.t-systems.com/v1/{project_id}/vpcs/{vpc_id}";
+get(ak, sk, url);
+
+//TODO: When creating a VPC, replace {project_id} in postUrl with the actual value.
+//String postUrl = "https://vpc.eu-de.otc.t-systems.com/v1/{project_id}/cloudservers";
+//String postbody ="{\"vpc\": {\"name\": \"vpc\",\"cidr\": \"192.168.0.0/16\"}}";
+//post(ak, sk, postUrl, postbody);
+
+//TODO: When querying a VPC, replace {project_id} in url with the actual value.
+//String url = "https://vpc.eu-de.otc.t-systems.com/v1/{project_id}/vpcs/{vpc_id}";
+//get(ak, sk, url);
+
+//TODO: When updating a VPC, replace {project_id} and {vpc_id} in putUrl with the actual values.
+//String putUrl = "https://vpc.eu-de.otc.t-systems.com/v1/{project_id}/vpcs/{vpc_id}";
+//String putbody ="{\"vpc\":{\"name\": \"vpc1\",\"cidr\": \"192.168.0.0/16\"}}";
+//put(ak, sk, putUrl, putbody);
+
+//TODO: When deleting a VPC, replace {project_id} and {vpc_id} in deleteUrl with the actual values.
+//String deleteUrl = "https://vpc.eu-de.otc.t-systems.com/v1/{project_id}/vpcs/{vpc_id}";
+//delete(ak, sk, deleteUrl);
+}
+ - (Optional) To call a service API of a sub-project or to add a self-defined header, perform the following steps:
- In the main method in the Demo.java file, replace project_id with the sub-project ID of the API.
//TODO: Test the API
+String url = "https://vpc.eu-de.otc.t-systems.com/v1/{project_id}/vpcs/{vpc_id}";
+get(ak, sk, url);
+ - Locate the following lines in the AccessServiceImpl.java file, delete "//" to activate the code line, and replace the sub-project ID with the actual one.
//TODO: Add special headers.
+//request.addHeader("X-Project-Id", "xxxxx");
+ - Repeat 4.b to add other self-defined headers.
+ - Compile and run the API calling code.
Find Demo.java in the left pane of the Package Explorer, right-click, and choose Run AS > Java Application.
+View the API call logs on the console.
+
+
+
+
Obtain the required information before calling APIs.
+
Required Information
+
Table 1 Required informationItem
+ |
+Parameter
+ |
+Description
+ |
+
|---|
+
+Service name
+ |
+serviceName
+ |
+Service name, for example, iam, vpc, and ecs.
+ |
+
+Region/Endpoint
+ |
+-
+ |
+Region and endpoint.
+See Regions and Endpoints.
+ |
+
+Project ID
+ |
+project_id
+ |
+Project ID, which is configured in the URI in most cases.
+For details about how to obtain the value of this parameter, see Obtaining a Project ID.
+ |
+
+username/password
+ |
+username/password
+ |
+Username and password, which are used to obtain a token in token authentication mode.
+ |
+
+AK/SK
+ |
+ak/sk
+ |
+AK/SK pair.
+It is used in AK/SK authentication mode.
+For details about how to obtain the value of this parameter, see Generating an AK and SK.
+ |
+
+uri
+ |
+uri
+ |
+Request path and parameters.
+Obtain the URI according to the API reference guide of each service.
+ |
+
+Domain Name
+ |
+-
+ |
+Account name, which is used to obtain a token in token authentication mode.
+For details about how to obtain the value of this parameter, see Obtaining the Domain Name and Domain ID.
+ |
+
+Domain ID
+ |
+X-Domain-Id
+ |
+Account ID, which is used to:
+- Obtain a token in token authentication mode.
- Access global services, such as IAM, DNS, and CDN, in AK/SK authentication mode. You must specify a domain ID in the header.
+For details about how to obtain the value of this parameter, see Obtaining the Domain Name and Domain ID.
+ |
+
+Sub-project ID
+ |
+X-Project-Id
+ |
+Sub-project ID, which is used in multi-project scenarios.
+For details about how to obtain the value of this parameter, see Obtaining a Project ID.
+ |
+
+
+
+
+
+
Obtaining a Project ID
A project ID needs to be specified in the URIs of some APIs. Therefore, you need to obtain the project ID before calling APIs. The following procedure describes how to obtain a project ID:
+
- Log in to the management console.
- Click the username and choose My Credential from the drop-down list.
On the My Credential page, view project IDs in the project list.
+Figure 1 Viewing project IDs
+In multi-project scenarios, expand the region, and obtain your sub-project ID from the Project ID column.
+
+
+
Obtaining the Domain Name and Domain ID
When you call APIs, your domain name and domain ID are required in some URLs. Obtain your domain name and domain ID on the console by performing the following steps:
+
- Log in to the management console.
- Click the username and choose My Credential from the drop-down list.
On the My Credential page, view the domain name and domain ID.
+Figure 2 Viewing the domain name and domain ID
+
+
+
Table 1 describes common status codes.
+
+
Table 1 HTTP request status codesReturn Value
+ |
+Description
+ |
+
|---|
+
+200 OK
+ |
+The request has been processed successfully.
+ |
+
+204 No Content
+ |
+The server does not return any information.
+ |
+
+400 Bad Request
+ |
+The server failed to process the request. Possible causes include:
+- The request could not be parsed by the server due to incorrect syntax.
- Request parameters are incorrect.
+ |
+
+401 Unauthorized
+ |
+The request requires user authentication. For example, the username and password are required.
+ |
+
+403 Forbidden
+ |
+You are forbidden to access the requested page.
+ |
+
+404 Not Found
+ |
+The request failed because the requested resource could not be found on the server.
+ |
+
+405 Method Not Allowed
+ |
+You are not allowed to use the method specified in the request.
+ |
+
+406 Not Acceptable
+ |
+The response generated by the server could not be accepted by the client.
+ |
+
+407 Proxy Authentication Required
+ |
+You must use the proxy server for authentication so that the request can be processed.
+ |
+
+408 Request Timeout
+ |
+The request timed out.
+ |
+
+409 Conflict
+ |
+The request could not be processed due to a conflict.
+ |
+
+410 Gone
+ |
+The requested resource is not available on the server and no known forwarding address is provided.
+ |
+
+412 Precondition Failed
+ |
+One or more conditions specified in the request header are not met when the server tests the conditions.
+ |
+
+500 Internal Server Error
+ |
+The server failed to process the request due to an unexpected condition.
+ |
+
+501 Not Implemented
+ |
+Failed to complete the request because the server does not support the requested function.
+ |
+
+502 Bad Gateway
+ |
+Failed to complete the request because the server has received an invalid response.
+ |
+
+503 Service Unavailable
+ |
+Failed to complete the request because the service is unavailable.
+ |
+
+504 Gateway Timeout
+ |
+The gateway timed out.
+ |
+
+
+
+
+
