To send a Web Application Firewall (WAF) API request, you must send an HTTP GET request to the WAF endpoint. You must add the request parameters that correspond to the API operation being called. After you call the API, the system returns a response. The request and response are encoded in UTF-8.

Request syntax

WAF API operations use the RPC protocol. You can call WAF API operations by sending HTTP GET requests.

The request syntax is as follows:
https://Endpoint/?Action=xx&Parameters
In the request:
  • Endpoint: the endpoint of the WAF API varies with the region.
    • Mainland China: wafopenapi.cn-hangzhou.aliyuncs.com
    • Outside mainland China: wafopenapi.ap-southeast-1.aliyuncs.com
  • Action: the operation that you want to perform. For example, to obtain a list of the domains added to WAF, you must set the Action parameter to DescribeDomainNames.
  • Version: the version of the API to be used. The current WAF API version is 2019-09-10.
  • Parameters: the request parameters for the operation. Separate multiple parameters with ampersands (&).

    Request parameters include both common parameters and operation-specific parameters. Common parameters include the API version and authentication information. For more information, see Common parameters.

The following example demonstrates how to call the DescribeDomainNames operation to obtain a list of the domains added to WAF.
Note To improve readability, the API request is displayed in the following format.
https://wafopenapi.cn-hangzhou.aliyuncs.com/?Action=DescribeDomainNames
&Region=cn
&InstanceId=waf_elasticity-cn-0xldbqtm005
&Format=xml
&Version=2019-09-10
&Signature=xxxx%xxxx%3D
&SignatureMethod=HMAC-SHA1
&SignatureNonce=15215528852396
&SignatureVersion=1.0
&AccessKeyId=key-test
&TimeStamp=2012-06-01T12:00:00Z
...

API authorization

To ensure the security of your account, we recommend that you call the WAF API as a RAM user. To call the WAF API as a RAM user, you must create an account for the RAM user and grant the account required permissions.

Signature method

You must sign all API requests to ensure security. WAF uses the request signature to verify the identity of the API caller.

WAF implements symmetric encryption with an AccessKey pair to verify the identity of the request sender. An AccessKey pair is an identity credential issued to Alibaba Cloud accounts and RAM users that is similar to a logon username and password. An AccessKey pair consists of an AccessKey ID and an AccessKey secret. The AccessKey ID is used to verify the identity of the user, while the AccessKey secret is used to encrypt and verify the signature string. You must keep your AccessKey secret strictly confidential.

You must add the signature to the Cloud Firewall API request in the following format:
https://endpoint/?SignatureVersion=1.0&SignatureMethod=HMAC-SHA1&Signature=CT9X0VtwR86fNWSnsc6v8YGOjuE%3D&SignatureNonce=3ee8c1b8-83d3-44af-a94f-4e0ad82fd6cf
Take the DescribeDomainNames operation as an example. If the AccessKey ID is testid and the AccessKey secret is testsecret, the original request URL is as follows:
https://wafopenapi.cn-hangzhou.aliyuncs.com/?Action=DescribeDomainNames
&Region=cn
&InstanceId=waf_elasticity-cn-0xldbqtm005
&TimeStamp=2016-02-23T12:46:24Z
&Format=XML
&AccessKeyId=testid
&SignatureMethod=HMAC-SHA1
&SignatureNonce=3ee8c1b8-83d3-44af-a94f-4e0ad82fd6cf
&Version=2019-09-10
&SignatureVersion=1.0
Perform the following operations to calculate the signature:
  1. Use the request parameters to compose a string-to-sign.
    GET&%2F&AccessKeyId%3Dtestid&Action%3DDescribeDomainNames&Region%3Dcn&InstanceId%3Dwaf_elasticity-cn-0xldbqtm005&Format%3DXML&SignatureMethod%3DHMAC-SHA1&SignatureNonce%3D3ee8c1b8-83d3-44af-a94f-4e0ad82fd6cf&SignatureVersion%3D1.0&TimeStamp%3D2016-02-23T12%253A46%253A24Z&Version%3D2019-09-10
  2. Calculate the HMAC value of the string-to-sign.
    Add an ampersand (&) to the end of the AccessKey secret, and use the result as the key to calculate the HMAC value. In this example, the key is testsecret&.
    CT9X0VtwR86fNWSnsc6v8YGOjuE=
  3. Add the signature to the request parameters:
    https://wafopenapi.cn-hangzhou.aliyuncs.com/?Action=DescribeDomainNames
    &Region=cn
    &InstanceId=waf_elasticity-cn-0xldbqtm005
    &TimeStamp=2016-02-23T12:46:24Z
    &Format=XML
    &AccessKeyId=testid
    &SignatureMethod=HMAC-SHA1
    &SignatureNonce=3ee8c1b8-83d3-44af-a94f-4e0ad82fd6cf
    &Version=2019-09-10
    &SignatureVersion=1.0
    &Signature=CT9X0VtwR86fNWSnsc6v8YGOjuE%3D