Whenever you update or patch a rule tree, PAPI allows you to save property rule or hostname data in a state that would later fail on activation, but by default it embeds guidance about each problem within the response. PAPI returns these error responses in the standard JSON Problem format. Two kinds of problems appear in success responses:
-
An
errorsarray notes any blocking problem that would prevent activation. You need to fix these before activating the property. -
A
warningsarray notes non-blocking, less severe issues. You can either modify the data in response, or acknowledge the set of warnings when later activating the property.
For example, when you try to PUT a rule tree that's missing required origin and cpCode behaviors, a 200 response identifies them as errors:
{
"accountId": "act_1-1TJZFB",
"contractId": "ctr_1-1TJZH5",
"groupId": "grp_15225",
"propertyId": "prp_173136",
"propertyVersion": 3,
"etag": "a9dfe78cf93090516bde891d009eaf57",
"errors": [
{
"type": "/papi/v1/errors/validation.required_behavior",
"title": "Missing required behavior in default rule",
"detail": "In order for this property to work correctly behavior Content Provider Code needs to be present in the default section",
"instance": "/papi/v1/properties/prp_173136/versions/3/rules#err_100",
"behaviorName": "cpCode"
},
{
"type": "/papi/v1/errors/validation.required_behavior",
"title": "Missing required behavior in default rule",
"detail": "In order for this property to work correctly behavior Origin needs to be present in the default section",
"instance": "/papi/v1/properties/prp_173136/versions/3/rules#err_101",
"behaviorName": "origin"
}
],
"rules": {
"name": "default",
"options": {
"is_secure": false
},
"children": [
{
"name": "Handle /my-path",
"criteriaMustSatisfy": "all",
"criteria": [
{
"name": "wildcard",
"value": ["/my-path"]
}
],
"behaviors": [
{
"name": "caching",
"behavior": "MAX_AGE",
"ttl": "1m"
}
]
}
]
}
}
Even though you can save the rule tree, you can't activate the property until you add the missing behaviors.
PAPI offers an option to skip potentially lengthy validation tests that would result in these errors and warnings. You'd still need to address the problems prior to activation, but this option allows you to modify and save data more quickly as a matter of routine throughout your development cycle. See Validation best practices for more information.
Rule tree errors
The API may release a wide range of validation errors based on the content of rule trees, many of which are detailed in the Validation errors section. A few unusual error scenarios are unique to PAPI:
-
As discussed in API versioning, you can freeze the API to use a specific set of behavior and criteria versions. If instead you specify the rule format that uses the
latestversions, behaviors and criteria silently update, and may produce errors if their validation requirements change. Other validation errors may remain even when properly updating from one rule format version to another. -
As discussed in the Advanced and locked features section, some behaviors and criteria are locked and read-only, and can only be modified with assistance from Akamai Professional Services. You get an error if you try to modify or move them elsewhere within the rule tree.
-
As discussed in the Rule Trees section and detailed in the behavior and criteria reference, some options may be required depending on the values of others. It's much easier to accidentally omit necessary values in the API than in the Control Center interface.
-
Some errors may reference schemas, which you can examine to determine each product's support for behaviors and criteria. They also list the full set of options for each, along with their expected data types. However, schemas don't represent dependencies among options.
Rule tree warnings
Aside from errors, PAPI more often returns a set of warnings after checking your chosen set of behaviors and criteria for identifiable logical inconsistencies.
Here is a typical warning, whose errorLocation is a URL fragment that can be interpreted as a JSON Pointer to help you locate the problem within the JSON tree you submitted:
"warnings": [
{
"type": "https://problems.luna.akamaiapis.net/papi/v1/validation/need_feature",
"errorLocation": "#/rules/behaviors/5",
"detail": "`Tiered Distribution` only applies to cacheable
content, but caching was never turned on."
}
]
Behaviors such as tieredDistribution and prefreshCache can only operate on cached content on edge servers. So, the warning identifies when the caching behavior isn't enabled. As another example, the cacheKeyIgnoreCase behavior allows requests for files and query parameters with mixed upper- and lower-case letters to resolve to the same cache key. If you pair that behavior with a criterion that doesn't specify a case-insensitive match, you'll be warned not to apply different behaviors to the same cached object, based on variations in upper- or lower-case in incoming requests.
These warnings often identify obvious logical problems, such as:
- You have exclusive sets of criteria when
criteriaMustSatisfyis set toall, or - You have nested criteria that can never execute because they're logically exclusive with their ancestor rules' criteria.
No validation mechanism can identify all potential bugs. So, you need to carefully step through the code. You can also request text/xml rather than application/json from the Property versions interface if you'd rather look at how a version's combined set of rules and hostnames translate to the Akamai metadata that's ultimately distributed to edge servers. Contact your Akamai Professional Services representative if you need help understanding the metadata syntax.
You need to acknowledge each warning before you activate a property. You can batch-acknowledge all warnings by setting the
acknowledgeAllWarningsflag using the create a new activation or deactivation operation. But, pay careful attention to any warnings before you activate a property version. If you don't, your site can experience serious problems.