Configuring Incapsula Application Delivery Rules API

Incapsula introduced application delivery rules to equip application owners with edge runtime tools to improve web application performance, efficiency and intelligence.

The rules can be configured through an intuitive user interface. However, in these following cases where a manual, user centric approach is not good enough, an automated, API-based approach is a better fit for examples like these when you are

• Repeatedly applying existing edge settings to newly deployed web sites or
• Applying new settings to a bulk of websites

This API is publicly available for all application delivery rules users.

API Basics

The API request is in a REST web service format, with the parameters specified in the HTTP request. The response content is provided in a JSON document. Requests include the authentication parameters which you can create in the API Settings section of your Account Details page:

• api_id
• api_key

Each response can include the following fields

• res – numerical response code, where non-zero indicates an error
• res_message – textual response message for an error response
• debug_info – specific information for an error response

with this sample format of the JSON document for an error response as shown below.

{
    "res": 2,
    "res_message": "Invalid input",
    "debug_info": {
        "name":"a datacenter with that name already exists",
        “id-info:”9089”
    }
}

Let’s look at how to use the API to implement several use cases. For this example, we’ll use the Curl tool, with a syntax that will send the data in an HTTP POST request.

Redirects

This rule permanently redirects users to a different site. For example, you may need to redirect your website visitors to a new site when old websites or pages have been retired. When a request matches the From URL of a redirect rule, Incapsula responds with your selected W3C 30x response code and redirects the client to the specified To URL .

This script adds this rule with the add operation, action parameter RULE_ACTION_REDIRECT, and these other parameters of the rule, as defined in the Site Management API.

• site_id
• name
• from
• to

#!/bin/sh
curl -X POST -d api_id=12593 -d api_key="64cc622a-9da5-4911-b389-c98a4997b6e1" -d site_id=1046225 -d name=fd -d action="RULE_ACTION_REDIRECT" -d response_code=301 -d from=*//oldsite.com -d to=$1://www.newsite.com https://my.incapsula.com/api/prov/v1/sites/incapRules/add

Sample response to the command, when successful, is

{"res":"0","status":"ok","rule_id":"22960"}

×

Apr 25 Upcoming Webinar

Build a Robust API Security Strategy in 2024 (APJ)

Register Now

Forwards

This rule automatically forwards users to another server. For example, when certain resources are located on a dedicated server such as graphics stored on an image server, all requests for these resources can be forwarded to that device. When the request is sent to a URL matching the filter, the request is forwarded to the target data center.

First let’s create that dedicated data center with this API command, with these other parameters of the rule, as defined in the Site Management API.

• site_id
• is_content – set to true

#!/bin/sh

curl -X POST "https://my.incapsula.com/api/prov/v1/sites/dataCenters/add?api_key=64cc622a-9da5-4911-b389-c98a4997b4a0&api_id=12574&site_id=1046252&name=DC1&is_content=true&server_address=321.32.4.12"

{"res":"0","status":"ok","datacenter_id":"1205485"}

Then this script adds this rule with the add operation, action parameter RULE_ACTION_FORWARD_TO_DC, and these other parameters of the rule, as defined in the Site Management API.

• site_id
• name
• filter
• dc_id

Replace DCID with ID of data center you created.

#!/bin/sh

curl -X POST "https://my.incapsula.com/api/prov/v1/sites/incapRules/add?api_id=22843&api_key=082ced47-cbf4-4488-a3d3-b852ab899133&site_id=78925765&name=forwardURL&action=RULE_ACTION_FORWARD_TO_DC&dc_id=1184390"

Sample response to the command, when successful, is

{"res":"0","status":"ok","rule_id":"22963"}

Rewrite URL

This rule rewrites a URL to a more customer friendly URL. For example, you might have a complex URL served by your origin which has little meaning to the user. You can define a customer friendly URL in Incapsula to be substituted to the original “unfriendly” URL. This not only improves user experience, but also helps increase your SEO rankings.

This script adds this rule with the add operation, action parameter RULE_ACTION_REWRITE_URL, and these other parameters of the rule, as defined in the Site Management API.

• site_id
• name
• from
• to

#!/bin/sh

curl -X POST -d api_id=12574 -d api_key="64cc622a-9da5-4911-b389-c98a4997b4a0" -d site_id=1046252 -d name=rewriteURL -d action="RULE_ACTION_REWRITE_URL" –d from=*/https://drive.google.com/drive/u/1/folders/0B0wiTVoXPQ1UV2N4THZCYkk0VTQ -d to=$1://www.mydocs http://my.incapsula.com/api/prov/v1/sites/incapRules/add

Sample response to the command, when successful, is

{"res":"0","status":"ok","rule_id":"22574"}

List Rules

Now that you’ve created your rules, you can use the List API to get a dump of the ruleset currently configured for a web site. Run this script to list and validate your rules,

#!/bin/sh

curl -X POST "https://my.incapsula.com/api/prov/v1/sites/incapRules/list?api_key=082ced47-cbf4-4488-a3d3-b852ab899086&api_id=22832&site_id=78925715"

The command response is in JSON format and displayed as:

You can now continue and use this data to replicate this ruleset to the next website.

Incapsula application delivery rules API has many applications. The four we showed will get you started. We would be happy to hear your story. Leave a comment and let us know how you use the Incapsula API.