The Visitor Prioritization API

Visitor Prioritization is a Cloudlet that helps IT and marketing users more efficiently prioritize access to their origin infrastructure. By slowing down the number of concurrent visitors your web servers handle, you can effectively ensure your origin infrastructure is not overwhelmed during peak periods.

The OPEN Visitor Prioritization API allows you to manage your Visitor Prioritization rules.

NOTE: If you are new to Visitor Prioritization, please use the OPEN Cloudlets API instead. The Cloudlets API supports all Cloudlets. The Visitor Prioritization API will be deprecated in the near future.

Prerequisites

Before working with this API, you should be familiar with the {OPEN} API Introduction.

Input/Output Formats

Various calls may require that you pass additional content to the API (e.g., a POST Body component) in API requests. In this case, you need to specify the application/x-www-form-urlencoded HTTP content type. The POST content must be URL encoded.

The Policy JSON object contains your rules. For all Policy objects sent to the server, use application/x-www-form-urlencoded as the content type, and this format: query=<url-encoded JSON document>, where the query= portion is not URL encoded. For example, the actual POST data for getAllPolicyInfoMaps will look something like this:

query=%7B%22policyManagerRequest%22%3A%7B%22command%22%3A%22getPolicyInfoMapUsingACGIDs%22%2C%22getPolicyInfoMapUsingACGIDs%22%3A%7B%7D%7D%7D

You also need to set the Content-Length header for all POST requests.

Response objects are represented with the JSON (JavaScript Object Notation) format.

Network List Elements

Network List elements must be valid IP addresses, CIDR blocks (v4 or v6), or geographic locations.

Attempts to add an IP/CIDR block to a geographic list (or vice versa) returns the 409 (Conflict error) HTTP error code.

Care should be taken to avoid rate-limiting constraints. If the API caller is rate-limited, the API returns the 429 (Too Many Requests) HTTP error code.

Available Operations

Action Operation API Endpoint
Policies
Create a Policy POST /config-visitor-prioritization-data/api/v1/policymanager?command=create
Clone a Policy POST /config-visitor-prioritization-data/api/v1/policymanager?command=create{?cloneId}
List Policies POST /config-visitor-prioritization-data/api/v1/policymanager?command=getAllPolicyInfoMaps
Get a Policy POST /config-visitor-prioritization-data/api/v1/policymanager?command=read
Modify a Policy POST /config-visitor-prioritization-data/api/v1/policymanager?command=update/{id}
Activations
Activate a Policy POST /config-visitor-prioritization-data/api/v1/policymanager
List Policy Activations POST /config-visitor-prioritization-data/api/v1/common/activation{?historyOnly}

Errors

Error responses return JSON objects such as the following:

HTTP/1.1 200

Content-Type: application/json
Reply Body:
{
    "responseCode": 0,
    "i18nCode": 0,
    "englishMessage": "additional non-http specific info where relevant"
}

The returned JSON object contains a responseCode member; therefore, the caller does not have to check HTTP headers. If the responseCode is 0 the request succeeded; otherwise, the request failed.

Policy Members

This section provides details on the Policy data members included in requests or responses.

Member Type Description
acgId String Akamai use only.
activatedProduction Boolean If enabled, the policy is activated in the production network.
activatedStaging Boolean If enabled, the policy is activated in the staging network.
activatedTest Boolean If enabled, the policy is activated in the test/QA network.
arlId String Also known as the fileId, this is the ID associated with the Akamai Resource Locator (ARL).
assetId String Akamai use only.
cloudletConfig Object Akamai use only.
cloudletId Number Akamai use only.
createDate Number The date this specific policy was created (milliseconds since epoch).
createdBy String The name of the user who created this specific policy.
description String The description of this specific policy, not assigned by Akamai.
fileId Number Also known as the arlId, this is the ID associated with the Akamai Resource Locator (ARL).
id Number The unique ID that corresponds to a specific policy.
immutable Boolean Akamai use only.
matchRules Array A JSON structure that defines the rules for this policy. This value is not assigned by Akamai.
policyCreateDate Number The date the initial policy was created (milliseconds since epoch).
policyCreatedBy String The user who created the initial policy.
policyDescription String The default description for every version of the policy. This is not assigned by Akamai.
policyId Number Akamai use only.
policyLastModifiedBy String The user who last modified the policy.
policyLastModifiedDate Number The date the initial policy was modified (milliseconds since epoch).
policyName String The name used for every version of this policy. This is not assigned by Akamai.
policyVersionId Number Also known as tapiocaIDs, this is the ID associated with a specific policy version.
tapiocaIDs Array Also known as policyVersionId, this is the ID associated with a specific policy version. The expected value is an array of integers.
version Number The specific version of this policy.

matchRules Members

The matchRules property contains all of your rules. Some example use cases:

  • Pass through all HTTP requests that end in jpg or png with a probability of 95%.

  • Pass through HTTP requests with the vanity/marketing pathname of /shoes with a probability of 5%.

A matchRules property includes the following members:

Member Type Description
end Number The end time (in milliseconds since the epoch) this match will be valid.
id Number Akamai use only.
matchURL String If using a URL match, this is the URL that Visitor Prioritization will use to match the incoming request.
matches Array See matches below.
name String The name of the rule.
passThroughPercent Number A value of –1 means send everyone to the waiting room. The range 0.000–99.000 specifies the percentage of requests that will pass through to the origin. The value of 100 means the request will always pass through to the origin.
start Number The start time (in milliseconds since the epoch) this match will be valid.
type String The type of Cloudlet. For Visitor Prioritization use the string vpMatchRule.
useIncomingQueryString Boolean If enabled, Visitor Prioritization passes through the request query string.

matches Members

Each object in the matches property defines potential conditions (caseSensitive, matchType, matchValue, negate). If all of the conditions you set are true, the edge server passes the request through to the origin server based on your passThroughPercent setting.

A matches property contains an array of objects with the following members:

Member Type Description
caseSensitive Boolean If enabled, the match is case sensitive.
matchOperator Enumeration You must set this to contains.
matchType Enumeration The type of match used, either hostname, path, extension, query, cookie, protocol, continent, countrycode, or regioncode.
matchValue String This depends on the matchType. If the matchType is hostname, then matchValue will be the fully qualified domain name, such as www.akamai.com. See the matchValue Examples section below.
negate Boolean If enabled, negates the match.

matchValue Examples

The matchValue members provide information about the match types used to conditionally pass through the request.

NOTE: Match types marked with an asterisk (*) support multiple space-separated values (not names).

matchType Description matchValue Example
continent The continent to match on. NA (See continent code listings)
cookie Cookie values to match on. name=value1
countrycode The country to match on. US (See country code listings)
extension* File extensions to match on. jpg png gif
hostname* Hostnames to match on. www.akamai.com
path* Paths to match on. /clothing/children/shoes/shoe1.jpg
protocol The protocol to match on. http
query* Query values to match on. name, name=value1, or name=value1 value2
regioncode The region within a country to match on, like a state or province. MA (See region code listings)

Java Policy Example

The following is an example of a Visitor Prioritization policy in Java:

import java.net.URL;
import java.net.URLEncoder;
import java.util.Collections;

import org.junit.Test;

import com.akamai.edgegrid.auth.ClientCredential;
import com.akamai.edgegrid.auth.DefaultCredential;
import com.akamai.edgegrid.auth.EdgeGridV1Signer;
import com.akamai.edgegrid.auth.RequestSigner;
import com.google.api.client.http.ByteArrayContent;
import com.google.api.client.http.GenericUrl;
import com.google.api.client.http.HttpContent;
import com.google.api.client.http.HttpHeaders;
import com.google.api.client.http.HttpRequest;
import com.google.api.client.http.HttpRequestFactory;
import com.google.api.client.http.HttpResponse;
import com.google.api.client.http.HttpTransport;
import com.google.api.client.http.apache.ApacheHttpTransport;

public class OpenTestReadVP {

    @SuppressWarnings({ "unused", "unchecked" })
    @Test
    public void testReadVisitorPrioritization() throws Exception {

        // Use the values from control.akamai.com
        // (CONFIGURE -> Manage APIs -> ...)
        String clientToken = "TODO";
        String accessToken = "TODO";
        String clientSecret = "TODO";
        String hostHeader = "TODO";
        String openServiceURLStart = "https://TODO.luna.akamaiapis.net";

        URL url = new URL(openServiceURLStart + "/config-visitor-prioritization-data/api/v1/policymanager");
        HttpTransport HTTP_TRANSPORT = new ApacheHttpTransport();
        HttpRequestFactory requestFactory = HTTP_TRANSPORT.createRequestFactory();
        String id = "514";
        String postData = "{\"policyManagerRequest\":{\"command\":\"read\",\"read\":{\"id\":\" + id + \"}}}";
        String postDataEncoded = "query=" + URLEncoder.encode(postData, "utf-8");
        byte [] contentBytes = postDataEncoded.getBytes();
        HttpContent content = new ByteArrayContent("application/x-www-form-urlencoded", contentBytes);
        HttpRequest request = requestFactory.buildPostRequest(new GenericUrl(url), content);
        HttpHeaders headers = request.getHeaders();
        headers.set("Host", hostHeader);

        ClientCredential credential = new DefaultCredential(clientToken, accessToken, clientSecret);
        RequestSigner signer = new EdgeGridV1Signer(Collections.EMPTY_LIST, 1024 * 2);
        HttpRequest signedRequest = signer.sign(request, credential);
        HttpResponse response = signedRequest.execute();
        String result = response.parseAsString();
        int breakpoint = 1;
    }
}