Script Control (Web Skimming Protection) – Rules API

This document describes standardized API for rulesets and rules which has initially been developed for Script Control/Web Skimming Protection rule management. Eventually it is meant to be used for all rule types.

Rules and rulesets

In order to facilitate various types of rulesets and organization, we have introduced the concept of hierarchical rulesets. Rulesets get associated with a team.

A ruleset is essentially a more general way of allowing us and our customers to map how our service works on their traffic, rather than forcing the single way of organizing by properties (groups of domains), as we have had previously. A ruleset that is defined to apply to a set of specific domains would be the equivalent of our current notion of property. But rulesets can be created to group rules with great flexibility. For example, a ruleset might be defined for end-user browsers, such as a ruleset applying to any requests from the Chrome browser, for example. Or with role-based access, rulesets could be defined for teams – a ruleset for the CDN team, another ruleset for the security team, another for the analytics team, and so forth. Different customers will have different ways of looking at their domains and apps, so this scheme will allow them to carve up how they configure the service in a way that makes sense to them, rather than being forced into grouping domains into properties.

One way to think of rulesets is to compare it to a computer filesystem. At the root level we can create any number of directories or folders. Within each of these we can create any number of subdirectories or subfolders, and so on, allowing us to organize the files in our computer's disk in whatever way makes sense to us. Similarly, in our configuration architecture, we will now allow a number of rulesets, each of which can be further broken down into sub-rulesets, to contain the rules that define behavior of delivery, security, and script control.

When creating rulesets, we supply an optional “parent” parameter which specifies the full path of the parent ruleset under which new ruleset is to be created. The same semantics apply to creating rules.

The ID of the ruleset is the full path from repository root folder (/config/request/rules) onwards. For example, /www or www, /botrs/bot-team-a, and so on. The last part of the ID represents the name of the ruleset.

Methods

GET .../rules?rulesets={path}&version=alpha

Get the list of rules.

Parameters

Parameter

Description

rulesets

The path to the ruleset that the rules reside in.

To get rules at the root level, we pass in rulesets=rules

To get rules within ruleset at the root level, we pass in rulesets=rules/ruleset-name

POST .../rules?rulesets={path}&message={message}&user={user_name}
&version=alpha

Create a rule.

Parameters

Parameter

Description

rulesets

The path to the ruleset that the rules reside in. Required.

To create a rule at the root level, pass in rulesets=rules

To create a rule within an existing ruleset at the root level, we pass in rulesets=rules/ruleset-name

message

A descriptive message about the rule

user_name

The user that is logged in. This is usually an email address.

The rule JSON object has the following form:

{
  "rules": [
    {
      "priority": "0",
      "type": "data",
      "rulecontenttype": "data",
      "definition": [rule_definition]
      "content": {
        "description": "",
        [rule_content]
      },
      "description": [rule_description]
    }
  ]
}

PUT .../rules?rulesets={path}&message={message}&user={user_name}
&id={rule_id}&version=alpha

Update an existing rule.

Parameters

Parameter

Description

rulesets

The path to the ruleset for the rule to reside in.

To modify a rule at the root level, pass in rulesets=rules

To modify a rule within an existing ruleset at the root level, we pass in rulesets=rules/ruleset-name

message

A descriptive message about the rule

id

The ID of rule that you are modifying

user

The user that is logged in. This is usually an email address.

The rule JSON object has the following form:

{
  "rules": [
    {
      "priority": "0",
      "type": "data",
      "rulecontenttype": "data",
      "definition": [rule_definition]
      "content": {
        "description": "",
        [rule_content]
      },
      "description": [rule_description]
    }
  ]
}

DELETE .../rules?rulesets={path}&id={rule_id}&message={message}
&user={user_name}&version=alpha

Delete an existing rule

Parameters

Parameter

Description

rulesets

The path to the ruleset for the rule to reside in.

To delete a rule at the root level, pass in rulesets=rules

To delete a rule within an existing ruleset at the root level, we pass in rulesets=rules/ruleset-name

message

A descriptive message about the rule deletion

id

The ID of rule that you are deleting

user

The user that is logged in. This is usually an email address.