Create Cache Control

This API is used to create cache control for website acceleration service.

Request

Request-Line

POST /cdn/v1.0/services/{serviceId}/cacheControl HTTP/1.1

Request Parameters

Path Parameters

Parameter	Type	Required	Description
serviceId	Integer	Mandatory	The unique identifier for the service for which the cache control policy will be created.

Body Parameters

Parameter	Type	Required	Description
policyName	String	Mandatory	Policy name for the cache control configuration.
matchUrlPath	Object	Mandatory	URL path matching configuration that determines which requests the rule applies to. See Match Url Path for details.
matchQueryString	Object	Optional	Query-string matching configuration used to refine which requests the rule applies to. See Match Query String for details.
priority	Integer	Mandatory	Priority weight for the rule. Rules with a higher weight take precedence. The weight must be a positive integer (greater than zero).
ttl	Long	Optional	Cache TTL (time-to-live) in seconds for content stored on the edge servers.
refererAcl	Object	Optional	Access control based on the Referer header. Defines a domain list and an allow/deny policy to control which referer domains can access the resource. See Referer Acl for details.
originAcl	Object	Optional	Access control based on the requesting origin. Defines a domain list and an allow/deny policy to control which referer domains can access the resource. See Origin Acl for details.
ignoreClientNoCache	Boolean	Optional	When true, ignores no-cache headers sent by the client. Default is false.
ignoreOriginNoCache	Boolean	Optional	When true, ignores no-cache headers sent by the origin server. Default is false.
ignoreQueryString	Boolean	Optional	When true, ignores URL query strings when caching content. Default is false.
enableXCache	Boolean	Optional	When enabled, responses from edge servers include an X-Cache header indicating whether the response was served from cache (e.g., HIT or MISS). Default is false.
noCache	Boolean	Optional	When true, content is not cached even if the origin indicates it is cacheable. Default is false.
autoGzipDisable	Boolean	Mandatory	Disable automatic Gzip compression on the CDN edge. Default is false.
responseHeaders	Array	Optional	List of response header configurations. See Response Headers for details.
varyMIMEs	Array	Optional	Enables the "vary for images" feature. A list of MIME types (e.g., image/webp, image/jpeg) that should be preferred for objects matched by this policy.
enabled	Boolean	Optional	Whether the policy is active. Default is true.

Object: Match Url Path

Parameter	Type	Required	Description
operator	String	Mandatory	Defines how to match the URL path. Supported values: prefix, regex, equals, suffix.
patterns	Array	Mandatory	List of patterns to match against the URL path.

Object: Match Query String

Parameter	Type	Required	Description
operator	String	Mandatory	Defines how to match the query string. Supported values: prefix, regex, equals, suffix.
patterns	Array	Mandatory	List of patterns to match against the query string.

Object: Referer/Origin Acl

Parameter	Type	Required	Description
aclType	String	Mandatory	Access control type. Support values: whitelist or blacklist.
domainList	Array	Mandatory	List of domain names to be allowed or blocked.

Object: Response Headers

Parameter	Type	Required	Description
name	String	Mandatory	Response header name.
operationType	String	Mandatory	Operation to perform on the response header. Supported values: add, replace or delete.
value	String	Optional	Response header value. Required when operationType is add or replace.

Response

Response Body

Parameter	Type	Description
policyId	Integer	Policy ID number for cache control.
policyName	String	Policy name for the cache control configuration.
matchUrlPath	Object	URL path matching configuration that determines which requests the rule applies to. See Match Url Path for details.
matchQueryString	Object	Query-string matching configuration used to refine which requests the rule applies to. See Match Query String for details.
priority	Integer	Priority weight for the rule. Rules with a higher weight take precedence. The weight must be a positive integer (greater than zero).
ttl	Long	Cache TTL (time-to-live) in seconds for content stored on the edge servers.
refererAcl	Object	Access control based on the Referer header. Defines a domain list and an allow/deny policy to control which referer domains can access the resource. See Referer Acl for details.
originAcl	Object	Access control based on the requesting origin. Defines a domain list and an allow/deny policy to control which referer domains can access the resource. See Origin Acl for details.
ignoreClientNoCache	Boolean	When true, ignores no-cache headers sent by the client. Default is false.
ignoreOriginNoCache	Boolean	When true, ignores no-cache headers sent by the origin server. Default is false.
ignoreQueryString	Boolean	When true, ignores URL query strings when caching content. Default is false.
enableXCache	Boolean	When enabled, responses from edge servers include an X-Cache header indicating whether the response was served from cache (e.g., HIT or MISS). Default is false.
noCache	Boolean	When true, content is not cached even if the origin indicates it is cacheable. Default is false.
autoGzipDisable	Boolean	Disable automatic Gzip compresstion on the CDN edge. Default is false.
responseHeaders	Array	List of response header configurations. See Response Headers for details.
varyMIMEs	Array	Enables the "vary for images" feature. A list of MIME types (e.g., image/webp, image/jpeg) that should be preferred for objects matched by this policy.
enabled	Boolean	Whether the policy is active. Default is true.

Status Codes, Error Codes and Error Messages

Status Code	Error Code	Error Message
400	Request.BadRequest	Bad request.
400	InvalidCustomer.IdEmpty	Customer ID cannot be empty or invalid.
400	InvalidService.IdIncorrect	Service ID is empty or invalid.
400	InvalidService.IdPermission	Service ID cannot be found or unknown.
400	Invalid.PolicyName	Policy name is required.
400	InvalidPolicy.MatchURLIncorrect	The matchUrlPath cannot be empty.
400	InvalidPolicy.Operator	Operator must be one of the following values: prefix, regex, equals or suffix.
400	InvalidPolicy.Patterns	Patterns cannot be empty or invalid.
400	InvalidPolicy.RefererAcl	Invalid AclType. must be whitelist or blacklist.
400	InvalidPolicy.AclDomainList	DomainList cannot be empty and must not contain empty values.
400	InvalidPolicy.AclDomainType	DomainList elements cannot start with '-'
400	InvalidPolicy.Priority	Priority is required and must be a positive integer.
400	InvalidService.VaryMiME	VaryMIMEs cannot be empty.
400	InvalidPolicy.ResponseHeader	ResponseHeaders cannot be empty or invalid.

Examples

Create Cache Control

Request

POST /cdn/v1.0/services/228657/cacheControl HTTP/1.1

{
    "policyName":"cacheInfo",
    "matchUrlPath":{
        "operator":"prefix",
        "patterns":["/"]
    },
    "matchQueryString":{
        "operator":"prefix",
        "patterns":["/"]
    },
    "varyMIMEs": ["image/webp","image/avif"],
    "priority":222,
    "ttl":3600,
    "refererAcl":{
        "aclType":"whitelist",
        "domainList":["www.1.com","example2.com"]
    },
    "originAcl":{
        "aclType":"whitelist",
        "domainList":["www.1.com"]
    },
    "ignoreClientNoCache":false,
    "ignoreOriginNoCache":false,
    "ignoreQueryString":true,
    "enableXCache":true,
    "noCache":false,
    "autoGzipDisable":false,
    "responseHeaders":[{
      "name": "Content-Type",
      "operationType": "add",
      "value": "application/json"
    }]
}

Successful Response Body

{
    "policyId": 262021,
    "policyName": "cacheInfo",
    "ttl": 3600,
    "refererAcl": {
        "aclType": "whitelist",
        "domainList": [
            "www.1.com",
            "example2.com"
        ]
    },
    "originAcl": {
        "aclType": "whitelist",
        "domainList": [
            "www.1.com"
        ]
    },
    "ignoreClientNoCache": false,
    "ignoreOriginNoCache": false,
    "ignoreQueryString": true,
    "enableXCache": true,
    "noCache": false,
    "autoGzipDisable": false,
    "responseHeaders": [
        {
            "name": "Content-Type",
            "value": "application/json",
            "operationType": "Add"
        }
    ],
    "matchUrlPath": {
        "operator": "prefix",
        "patterns": [
            "/"
        ]
    },
    "matchQueryString": {
        "operator": "prefix",
        "patterns": [
            "/"
        ]
    },
    "varyMIMEs": [
        "image/webp",
        "image/avif"
    ],
    "priority": 222,
    "enabled": true
}