Akamai Content Control Interfaces

Content Control Utility (CCU)

Content Control Utility SOAP API (CCUAPI)
Enhanced Content Control Utility (ECCU)
ECCU File Upload
ECCU Publisher (PublishECCU)

August 26, 2008

 Akamai Technologies, Inc.
Akamai Customer Care: 1-877-425-2832 or, for routine requests, email [email protected]
Akamai EdgeControl, for customers and resellers: http://control.akamai.com

US Headquarters
8 Cambridge Center
Cambridge, MA 02142
Tel: 617.444.3000
Fax: 617.444.3001
US Toll free 877.4AKAMAI (877.425.2624)

For a list of offices around the world, see:

http://www.akamai.com/en/html/about/locations.html

Akamai Content Control Interfaces

Copyright © 2003–2008 Akamai Technologies, Inc. All Rights Reserved.
No part of this publication may be reproduced, transmitted, transcribed, stored in a retrieval system or translated into any language in
any form by any means without the written permission of Akamai Technologies, Inc. While every precaution has been taken in the prep-
aration of this document, Akamai Technologies, Inc. assumes no responsibility for errors, omissions, or for damages resulting from the
use of the information herein. The information in these documents is believed to be accurate as of the date of this publication but is sub-
ject to change without notice. The information in this document is subject to the confidentiality provisions of the Terms & Conditions
governing your use of Akamai services.
Akamai, EdgeComputing, and EdgeControl are registered service marks of Akamai Technologies, Inc. Other products or corporate
names may be trademarks or registered trademarks of other companies and are used only for the explanation and to the owner’s benefit,
without intent to infringe or to imply any endorsement of Akamai or its services by, or relationship between Akamai and, the owners of
such marks or to imply that Akamai will continue to offer services compatible with technology offered by such owners.
Java is a trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries.
Contents
CHAPTER 1. INTRODUCTION • 5
About the Content Control Mechanisms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5
About the CCU and ECCU . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6
Removal-based . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6
Invalidation-based . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6
Best Practices Considerations: Which Interface to Use, and Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . .7
CCU Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7
ECCU Limitations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8
Refresh or Remove by CP Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8
Refresh Specific URLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9
Refresh by Directory or Extension . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9
Refresh by More Complex Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9
Refresh Without Configuration File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9
A Summary Comparison of the Tools. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10
CHAPTER 2. CONTENT CONTROL UTILITY • 11
Before You Begin. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11
Using the Content Control Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12
Submitting Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12
About the Data Entry and the File Upload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13
If You Upload a File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14
If You Purge By CP Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14
On-Screen Submission Confirmation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15
Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16
CHAPTER 3. CONTENT CONTROL UTILITY SOAP API • 19
Supported Akamai Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .19
Using CCUAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .20
Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .20
Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .20
Using CCUAPI with Perl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .20
Perl-Specific Prerequisites. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .20
Using CCUAPI with Perl. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .21
Using CCUAPI with Visual Basic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .21
VB-Specific Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .21
VB Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .21
Using CCUAPI with Java and Axis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .22
CCUAPI Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .25
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .25
Function Detail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .25
Function Output. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .26
Sample Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .26
Result Codes and Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .27

Akamai Content Control Interfaces. Akamai Confidential. NDA Required for Release. 3
CHAPTER 4. ENHANCED CONTENT CONTROL UTILITY • 29
Before You Begin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Before You Upload ECCU Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Using the ECCU. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Viewing Previous Refresh Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Resubmitting a Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
About the Data Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
ECCU Status Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Informational Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
CHAPTER 5. ECCU PUBLISHER (PUBLISHECCU) • 35
ECCU Publisher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
CHAPTER 6. ABOUT DIGITAL PROPERTIES • 37
The PropertyName, Type, and Exact / Inexact Match. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Digital Property Attributes Configured in Setup, Not in These Interfaces . . . . . . . . . . . . . . . . . . . . . . . . 37
The Digital Property and the ARL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Exact Match or RHS? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
CHAPTER 7. ENHANCED CCU REQUEST FORMAT • 39
Format of an Enhanced CCU Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Rules for Proper Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Revalidation Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Based on the Digital Property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Based on Host Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Based on Directory Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Based On File Extension. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Best Practices in Requests: Use Space-Separated Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
The Revalidate Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Using Multiple Revalidate Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
About Epoch Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Match Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Summary of Matches Used to Revalidate Content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Path Matches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
recursive-dirs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
sub-dirs-only. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
this-dir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
filename . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Request Property Matches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
ext. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
cookie . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
cpcode-range. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
arltype. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
request-header. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
request-type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
query-string . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
typecode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Response Property Matches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
response-header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
4 Akamai Content Control Interfaces. Akamai Confidential. NDA Required for Release.
Chapter 1. Introduction
About the Content Control Mechanisms • 5
In This Chapter
About the CCU and ECCU • 6

Best Practices Considerations: Which Interface to Use,

and Limitations • 7
A Summary Comparison of the Tools • 10

About the Content Control Mechanisms

This document discusses the content control interfaces, which can be used to refresh
Akamai-served content. At Akamai®, the phrase content control refers to the control
over the refreshing or removing of objects cached in the Akamai network.
When you serve content through the Akamai network, one significant benefit is the
ability to cache content at the “edge” of the internet, that is, near the end user. The
normal method to refresh or replace the content is to set a TTL (time-to-live) in
cache for objects, which you can set by way of max-age type response headers, by con-
figuration files, or by encodings in the ARL (Akamai Resource Locator).
When the TTL expires, an Akamai node receiving a client request checks with the
origin using a conditional HTTP GET (also called an If-Modified-Since, or IMS,
GET request). If the object has changed, the origin server sends the new version; oth-
erwise, the origin sends an HTTP 304 Not Modified response, and Akamai serves the
cached instance of the object. Akamai provides numerous options and variations on
this scenario, but that is the basic mechanism.
When you need to manually refresh the content and not wait for TTL expiration,
Akamai provides two basic mechanisms to meet different needs and preferences, and
the basic mechanisms have a variety of interfaces you can use:
• Content Control Utility (CCU)—allows you to specify objects by URL/ARL
(Akamai Resource Locator), or by CP Code, to remove from cache and refresh
from the origin.
The CCU can be used as a Web interface on Akamai EdgeControl and as a
SOAP-based API (CCUAPI).
• Enhanced Content Control Utility (ECCU)—allows you to specify objects to
refresh by rules using path and extensions or other, more complex criteria. There
are three ways to use ECCU:
- Web interface on Akamai EdgeControl. Using the Web interface, you can
specify path and extension rules only.
- File upload, using a function on Akamai EdgeControl. Uploading ECCU
files allows you to specify more complex rules by which objects will be

Akamai Content Control Interfaces. Akamai Confidential. NDA Required for Release. 5
Introduction

refreshed—not only path or extension, but also by the request header or

method, protocol, or other criteria.
- ECCU Publisher (PublishECCU) is an EdgeControl Web Service that pro-
vides for uploading an ECCU file using a SOAP API, so that you can create
a local programmatic interface.

About the CCU and ECCU

Both the CCU and ECCU need to propagate refresh instructions through the Aka-
mai network. For CCU this normally takes about 10 minutes; if you submit over 200
ARLs it takes longer to process them all. For ECCU the normal time is 20–40 min-
utes; ECCU takes longer than CCU due to a different set of safety checks performed.
The differences between the mechanisms, at the basic level, are:
• The CCU and CCUAPI provide for removing and refreshing specific objects, for
example, as specified by URL or ARL or all objects under a CP code, using
removal-based or invalidation-based refresh. The CCU can handle many thou-
sands of requests per day.
• The ECCU provides for invalidation-based refresh by rules such as date/time,
path, and extension. The ECCU file upload and PublishECCU provide for
invalidation by criteria beyond path and extension such as request header, request
method or protocol.

Removal-based Removal-based means that when the Akamai edge server receives a client request, the
specified objects are removed from cache and a full GET is sent to the origin to fetch
the object and refresh the cache.

Invalidation-based Invalidation-based means that when the edge server receives a client request, it sends
an If-Modified-Since, a conditional GET, to the origin. The edge server will remove
and replace the cached object only if a newer version is found on the origin.

ECCU Matches and the purge.data File

When you create an ECCU request, the requests add to or replace matches in a
purge.data XML file, a file created and maintained for your ECCU matches. The
ECCU match refers to the refresh rule you set, for example, /bin/images/*.gif, .
The match also includes the revalidate timestamp. Note that the match refers to the
rule, not to the files matching the rule. For example, /bin/images/*.gif is a match—
not /bin/images/file1.gif, file2.gif, etc.
ECCU matches are applied to every request for that host header, which can impact
performance if you have a great many unique matches. Objects are not refreshed at
the origin unless the timestamp shows them to be stale, of course.
Your purge.data file persists, and the code lines with the matches persist until they are
replaced. Matches are replaced if a the new match includes the old at a parent level.
For example, if you previously used /bin/images/*.gif as a match but you are cur-
rently submitting a revalidation request that includes /bin/*.*, the latter will replace

6 Akamai Content Control Interfaces. Akamai Confidential. NDA Required for Release.
 About the Content Control Mechanisms

the former, assuming the timestamp is for a current date and time. Matches are
replaced, or pruned, when there are matches with more recent timestamps.
Since requests persist in the purge.data, the file will grow without bound without
maintenance. To prevent growth to a point that damages performance, Akamai
prunes requests using a match of /*.* (all directories, all extensions) with a timestamp
as distant in the past as possible to slightly reduce file size. Akamai does this automat-
ically when the file grows beyond a configurable size, for example, 250KB.
ECCU File Structure and Digital Properties
The ECCU file structure, used in the Enhanced CCU, ECCU file upload, and Pub-
lishECCU, is discussed in “Enhanced CCU Request Format” on page 39. The
ECCU file is an XML structure that allow you to specify the rules by which content
will be refreshed. For PublishECCU and ECCU file upload, you create ECCU files,
while in the ECCU you specify the properties in the browser UI but can then view
the ECCU structure which is created for you by the Web interface.
When you work with the ECCU structure, you work with digital properties, digital
property types, and exact/inexact matches. These are described in “About Digital
Properties” on page 37.

Best Practices Considerations: Which Interface to Use, and Limitations

The CCU and CCUAPI applications are best suited to use when you have a set of
individual objects whose name (ARL or URL) is known in advance. You can remove
many thousands of individual objects using CCU, which efficiently removes the con-
tent from the Akamai edge servers in batches. If there are more than about 10,000
objects, you should consider purge by CP code. The ECCU is best used when you
need to use rules such as directory or extension or more complex rules.
Whenever you use any content control mechanism, make sure to update the content on
your origin server before submitting the request. Refresh instructions reach the edge servers
within seconds even though the final confirmation of completion takes minutes to arrive.

General Limitations All the CCU and ECCU applications propagate refresh or removal instructions to
every edge server in the Akamai network and await confirmation from all of those
servers that the content has been removed or invalidated. These mechanisms are not
meant to substitute for using TTL (time-to-live) settings in your configuration or in
response headers, which better maximize system and content delivery performance.

Load Spikes When using CCU or ECCU, you need to be aware of the possibility of creating a
spike in the load on your origin as many concurrent requests come in for removed or
invalidated objects. Full GETs (removal-based) may cause more load than conditional
GETs (invalidation-based) unless all objects have changed. A mitigation is to space
refresh requests over time—not specifying all objects in one submission

CCU Limitations One limit is that files submitted for CCU requests should contain no more than
about 100 URLs of about 400 characters in length. If you receive a “Request Entity
Too Large” error, split your file into smaller files and try again."

Akamai Content Control Interfaces. Akamai Confidential. NDA Required for Release. 7
Introduction

You can submit any number of files containing about 100 URLs, but you should
have no more than 10,000 outstanding requests at any one time. If you receive a
Code 332 error, which indicates you have exceeded that limit, you should wait about
10 minutes and try again.
The CCU request does not persist—it is executed by the edge server and then “for-
gotten.” Any content matching the CCU request is removed one time. If another
request comes for the content, a fresh copy will repopulate the cache.

ECCU Limitations Using ECCU applications, Akamai recommends that you limit the number of
matches to 250 or fewer—see “ECCU Matches and the purge.data File” on page 6
for a definition of ECCU matches. Submitting more than 250 invalidation requests
at one time can result in a “global invalidation” –revalidating all content for that host
header. The way to avoid this is to invalidate multiple objects or paths in one request,
as described on page 42.
You should avoid matching on content that is unique to a single or few users, and
submit no more than 100 requests per day. This recommendation is not an absolute
maximum, and more matches or requests on a particular day may be processed with-
out incident, but consistently exceeding the recommended limits may result in
degraded performance as measured by timely refreshing of the objects.
The purge.data file consumes server memory to read, parse, and hold the resulting
parse tree in memory. Thus, a large number of ECCU matches—a large purge.data
file—may lead to decreased performance showing as longer service times for your
content. It is best to keep purge.data files small. You can occasionally prune your
purge.data file with a match of “/*.*” and a timestamp of, for example, two weeks ago
to keep the file size down. You’d need to use ECCU file upload or the SOAP API to
specify a timestamp other than “now.” The pruning will cause a higher forward
request rate for your objects matched by “/*.*” that were not otherwise revalidated,
but in practice, this small increase has not been significant enough to cause problems.
Akamai will automatically prune requests using a match of /*.* (all directories, all
extensions) with a timestamp as distant in the past as possible to slightly reduce file
size, when the purge.data file grows beyond a configurable size (for example, 250KB)
Note that you cannot otherwise delete matches from the purge.data file. The
“Delete” instruction in the PublishECCU API does not delete matches from the
purge.data file, it removes ECCU requests from view in the Web UI.
Finally, note that the ECCU invalidates content, it does not remove it. If you need to
actively remove objects from cache you must use the CCU application.

Corner Cases One “corner case” exists if an object is fetched and cached by way of two different
digital properties. Under removal-based refresh, any client request for the object will
cause it to be re-fetched.
Under the invalidate-based method, however, a client request for the object that does
not match the criteria you set in the ECCU file will not cause it to be refreshed. The

8 Akamai Content Control Interfaces. Akamai Confidential. NDA Required for Release.
 About the Content Control Mechanisms

object is refreshed only when a client request occurs that matches the criteria you set
in the ECCU file or Enhanced CCU submission.

Refresh or Remove The CCU and CCUAPI applications can remove or invalidate all objects with a given
by CP Code CP code. This is best used when all or almost all objects have been modified. If only
some have been modified, you should not use the CP code so the cached object con-
tents do not have to be re-fetched from the origin server. When you refresh by CP
Code, you need to be aware of the possibility of creating a spike in the load on your
origin, as many concurrent requests come in for refreshed objects.

Refresh Specific The CCU is best suited for refreshing specific URLs, and it is strongly recommended
URLs that you use it rather than ECCU, because of the advantages of speed, the option to
directly invalidate, and efficiency on the network.

Refresh by Directory The ECCU is best suited when you can best identify by objects by directory or file
or Extension extension. The ECCU file upload UI and ECCU Publisher also provide this func-
tionality, of course. The ECCU application works best with a few matches that cover
broad categories of content. For example, “/images/*.gif ” can easily be invalidated
across all edge servers with the ECCU application.

Refresh by More The ECCU file upload and ECCU Publisher provide for invalidation by such criteria
Complex Properties as the Request header, Request method or protocol, contents of a query string, and
other criteria. See “Enhanced CCU Request Format” on page 39.

Refresh Without ECCU file instructions apply to content configured for control with edge server con-
Configuration File figuration files. If your content does not use a configuration file—for example, some
content served through Freeflow or Freeflow Streaming—you must use CCU.

Akamai Content Control Interfaces. Akamai Confidential. NDA Required for Release. 9
Introduction

A Summary Comparison of the Tools

To summarize the preceding discussion, this table lists the various interfaces that can
be used to manually refresh cached content on the Akamai network. The interfaces
are listed from top to bottom: the least complex at the top to the most flexible and
functional but most complex to use, at the bottom.

Table 1: Comparing and Contrasting Akamai Content Control Tools

Tool Description Advantages Disadvantages

CCU A control.akamai.com Easiest-to-use UI, quickest, Must specify each object to be

Content Control web page that allows removal-based or invalidation removed; For example, cannot
Utility UI you to specify objects based. Optional email notification specify a directory by wildcard.
to remove from cache, of results.
or to remove objects
by CP Code.

Content Control Same as the CCU UI, You don’t have to log in to con- Same as CCU UI. Also, there is
Utility API (CCUAPI) but a SOAP-based API. trol.akamai.com and can set up set up involved in using SOAP
your own interface. API and, if desired, creating an
additional interface.

ECCU A control.akamai.com Easy to use rule-based UI. Pro- Cannot specify individual
Enhanced Content Web UI that allows vides for inclusion of sets of objects. Requests persist in a
Control Utility you to specify refresh- objects by directory or exten- purge.data file, replaced only
ing objects by rules sion—not individual objects—to by requests with more recent
involving path and refresh by invalidation. timestamps using the same
extensions. matches.

ECCU file upload Using the ECCU Web More flexible and complex than Need to create the ECCU file,
UI, you can upload Enhanced CCU GUI. Can fine get the syntax right, etc. More
ECCU files containing tune refreshing based on request flexibility and power means
rule-based instruc- headers, request method, and more potential for errors. Uses
tions beyond path and other criteria. the same purge.data file as the
extension. ECCU GUI.

PublishECCU An EdgeControl Web Provides essentially the same You need to set up to use the
Service SOAP-based functionality as the ECCU file SOAP API; otherwise the same
API that allows you to upload UI, since it provides for as ECCU file upload.
upload ECCU files. uploading ECCU files, but as a a
SOAP-based API, you can develop
and use a local interface instead
of using a browser to log on Aka-
mai EdgeControl.

If you have further questions about content delivery and invalidation options please
contact your Akamai representative or Akamai Customer Care.

10 Akamai Content Control Interfaces. Akamai Confidential. NDA Required for Release.
Chapter 2. Content Control Utility

Using the Content Control Utility • 12

In This Chapter
Submitting Requests • 12
About the Data Entry and the File Upload • 13
On-Screen Submission Confirmation • 15

Troubleshooting • 16

The Content Control Utility (CCU) is a Web interface available on Akamai Edge-
Control, control.akamai.com that allows you to specify the refreshing of specific
cached objects, or to remove all objects specified by CP Codes.
The Content Control Utility (CCU) provides the option of using invalidation-based
or removal-based refresh. See page 6 for a discussion of the differences between these
two methods.
The Content Control Utility is available for most objects delivered through Akamai.
For streaming services, removal of QuickTime, Real, and Windows Media objects is
supported. Requests are propagated through the Akamai network, and most removals
are completed within 10 minutes of the request.

One limit is that files submitted for CCU requests should contain no more than
about 100 URLs of about 400 characters in length. If you receive a “Request Entity
Too Large” error, split your file into smaller files and try again."
You can submit any number of files containing about 100 URLs, but you should
have no more than 10,000 outstanding requests at any one time. If you receive a
Code 332 error, which indicates you have exceeded that limit, you should wait about
10 minutes and try again.
Also, the utility uses a software throttle to release requests to the network over time
rather than send all at once, so that the more ARLs/URLs in a request, the longer it
can take to complete.
The CCU request does not persist—it is executed by the edge server and then “for-
gotten.” Any content matching the CCU request is removed one time. If another
request comes for the content, a fresh copy will repopulate the cache.

Before You Before you use the Content Control Utility:

Begin You’ll need to have access to control.akamai.com. If you don’t have access to Edge-
Control or to this Content Control Utility, check with your Akamai representative.
For a discussion of best practices—when to use this interface or a different content control
interface, the advantages, disadvantages, and limitations of each, please see the Introduc-
tion to this guide, and in particular the material beginning on page 7.

Akamai Content Control Interfaces. Akamai Confidential. NDA Required for Release. 11
Content Control Utility

Using the Content Control Utility

Submitting To submit refresh requests using the Content Control Utility:

Requests 1. Log in to control.akamai.com.
2. In the sidebar, click the product link for the product you want to work on.
3. Under the product, click the Content Control Utility link to display the Con-
tent Control Utility page.
The Content Control Utility page contains both the CCU (Refresh by URL) and
ECCU applications (Refresh by Directory and File Extension). The CCU option
is the default; if it isn’t displayed, click the Refresh by URL link.

Figure 1. Refresh by URL (the CCU main page)

4. Choose the basic refresh method:
- Enter a list of ARLs/URLs you want to remove, OR
- Browse for a file containing the list of ARLs or URLs you want to remove
OR
- Indicate the CP code for which you want to purge all associated content.
Note that ARLs/URLs must be full, not relative, and must include the protocol,
which can be http://, https://, rtmp://, or mms://. For example:
http://www.example.com/graphics/picture.gif is OK
graphics/pictures.gif is NOT OK.

12 Akamai Content Control Interfaces. Akamai Confidential. NDA Required for Release.
 Using the Content Control Utility

5. Indicate the Network on which to perform the refresh: Production or Staging.

Staging refers to the Edge Staging Network (ESN).

6. Indicate the Refresh method: purge or invalidate.

Figure 2. The Content Control Utility page.

7. Optionally, enter email addresses for notifications of the results of your request.
8. Click the Start Refreshing Content button.

About the Data Entry and the File Upload

The following guidelines apply to the data entry for the ARLs and URLs and to the
email addresses.

About the Data Entry for ARLs or URLs

When identifying objects to be removed from the Akamai network, note that you can
specify either Akamai Resource Locators (ARLs) or Uniform Resource Locators
(URLs). ARLs are discussed in “The Digital Property and the ARL” on page 37.
When entering requests to remove streaming media objects, you must enter the ARL/
URL of the actual streaming object, such as rtsp://… or mms://…. CCU does not
support entry of the metafile URL and will not remove the streaming media objects
referenced in the metafile.

Akamai Content Control Interfaces. Akamai Confidential. NDA Required for Release. 13
Content Control Utility

Specify URLs if you have an Akamaized domain and have CNAMED your site.
These entries look like standard URLs because Akamai- and object-specific data
reside in metadata for an Akamaized domain.
When you enter the ARLs/URLs to be removed in the ARLs/URLs field, you must
enter only one per line. You can specify full ARLs that indicate the Akamai network
and your CP code or use Akamaized host names in a URL. One limit is that files sub-
mitted for CCU requests should contain no more than about 100 URLs of about 400
characters in length. If you receive a “Request Entity Too Large” error, split your file
into smaller files and try again. You can submit any number of files containing about
100 URLs, but you should have no more than 10,000 outstanding requests at any
one time. If you receive a Code 332 error, which indicates you have exceeded that
limit, you should wait about 10 minutes and try again.

If You Upload a File Rather than list the objects, you can upload a text file containing the list of ARLs/
URLs to be removed. ARLs/URLs identified in the text file must also be one to a line.
Make sure that lines do not wrap and that there is a return character after each ARL.
The same limits apply (see the previous paragraph).
If You Purge By CP Rather than identifying the specific content to be removed, you can choose to remove
Code all content associated with one or more CP codes; the CP codes associated with your
Akamai EdgeControl login will be listed for your selection.
Caution: Removing or invalidating all objects under a CP code or top-level directory
can cause high load on your origin server. All Akamai edge servers will fetch or revali-
date these objects when next requested by an end user.

Removing Content or Invalidating Content

If you choose to remove content from the Akamai network, Akamai edge servers will
re-retrieve the content from the origin server the next time they receive a request from
one of the specified URLs.
If you choose to instead mark the content as invalidated, Akamai edge servers will
revalidate the freshness of the content with an HTTP conditional GET (If-Modified-
Since) request the next time they receive a request for one of the specified URLs. If
the content has changed, the origin server will return a fresh copy of the content. If
the content has not changed, the origin server will return an HTTP 304 Not Modi-
fied response, using less network bandwidth than if content were returned.

About the Email Address(es) and Notification

You can optionally choose to enter e-mail addresses to which notifications of a com-
pleted request should be sent. You can enter multiple e-mail addresses separated by
commas, or you can choose not to be notified. Messages will be posted to the
addresses, for example:
This message is to confirm your Akamai content removal request (101277051) has
been processed by all active servers on our network.
Please contact us (877-4-AKATEC) if you have any questions or require further
assistance.
Thank you from Akamai Customer Care.

14 Akamai Content Control Interfaces. Akamai Confidential. NDA Required for Release.
 Using the Content Control Utility

On-Screen Submission Confirmation

Besides the email notifications, the Content Control Utility provides an on-screen
message telling you whether your submission was accepted or rejected.
This message contains a Request ID you should keep track of. If you need to contact
Akamai Customer Care with a question of problem about the purge request, having
the request ID code on hand greatly facilitates the process.

Akamai Content Control Interfaces. Akamai Confidential. NDA Required for Release. 15
Content Control Utility

Troubleshooting
This section discusses some common issues that can arise when using the Content
Control Utility. Most deal with small errors in entering the content removal request
and are easily remedied. Use this information to quickly diagnose and troubleshoot a
problem.
If you are unable to diagnose or fix an issue, or need assistance with user names and
passwords, please call your Akamai Account Manager, or contact Akamai Customer
Care at 877-4-AKATEC (877-425-2832) or [email protected].
I am unable to access the Content Control Utility.
Akamai EdgeControl users must have tech or admin roles and must have the appro-
priate items in their contracts to access Content Control Utility. If you have the
appropriate role and line item and still cannot access the link, contact Customer
Care. If you do not have the appropriate role or line item and feel you should, contact
your Akamai Account Manager for further discussion.
I get the error 'You have exceeded your maximum number of outstanding purge ARLs'.
Your most recent request caused you to have over 10,000 total ARLs/URLs in the
queue for purging. You cannot have more than 10,000 ARLs/URLs pending at once.
Wait a few minutes to give some of your pending requests time to complete, then
submit your request again.
I get the error message 'Badly formatted ARL'.
One of the following issues exists:
• The ARLs are not formatted correctly. Whether you manually submitted ARLs
to the interface or uploaded a text file containing the ARLs to be removed, each
ARL must be on its own line. Make sure there is a line break after each ARL. Use
caution when copying and pasting ARLs from email or other files. Doing so
sometimes causes the text to wrap, thereby breaking the ARLs. Fix the errors and
try to resubmit the request.
• You've uploaded an incompatible file format. Content Control Utility accepts
files in text format only. If you are uploading a file of ARLs to be removed, make
sure the file is in text (.txt) format. Fix the errors and try to resubmit the request.
I get the error 'Illegal or unauthorized ARL'.
One of the following issues exists:
• You've uploaded an incompatible file format. Content Control Utility accepts
files in text format only. If you are uploading a file of ARLs/URLs to be removed,
make sure the file is in text (.txt) format. Fix the errors and try to resubmit the
request.
• You are not authorized to remove these ARLs/URLs. You can only request
removals of domains associated with your cpcode by your Account Manager.
Contact your Account Manager for further assistance.

16 Akamai Content Control Interfaces. Akamai Confidential. NDA Required for Release.
 Troubleshooting

The CCU submission form is hanging instead of submitting the request, and I’m not
receiving a request confirmation.
Try to make your content removal request again in approximately 15 minutes. If you
still receive an error, contact Akamai Customer Care.
I haven't received notification that my content removal is complete.
One of the following issues exists:
• You did not enter any e-mail addresses when you made the removal request. If
you wanted to be notified when a removal is complete, you must enter e-mail
addresses at the time of the request. Content Control Utility does not use e-mail
addresses associated with your login information for notifications.
• The notification e-mail addresses are invalid. You may have entered invalid e-
mail addresses for notification of a completed content removal, but that doesn't
necessarily mean that the content hasn't been removed. Contact Customer Care
with your request ID numbers to check whether the process is complete.
• It’s possible that the content removal has occurred, but the Akamai user notifica-
tion process is unable to confirm this removal. If you suspect this is occurring,
check with Contact Customer Care with your request ID to check on the status
of your request.
• The content removal has not yet occurred. When you submit a content removal
request, the confirmation page will indicate an estimated time for completion.
Check this time to see if the content removal should be complete. If you have
further concerns, please contact Customer Care.
I’ve received email notification that my content removal is complete, but I’m still seeing
old images.
One of the following issues exists:
• Your browser could be caching old images. Clear the cache in your browser and
check the images again.
• Your Web servers could still contain old content. Make sure you replace old files
with fresh content files on your Web server before you make a content removal
request. Otherwise, after Akamai removes the content from Akamai servers, the
old content will get re-distributed. If you didn't change the old content on your
Web servers, replace it now and re-request the content removal.
• When removing streaming media content, make sure you have entered the ARL/
URL for the actual streaming media object. Entering metafile URLs will not
remove the content referenced in those metafiles.
I get an error that says Purging Service Not Available.
Try to make your content removal request again in approximately 15 minutes. If you
still receive an error, contact Akamai Customer Care.
I get an error containing the words 'Internal Error'.
Please contact Akamai Customer Care at 1-877-4-AKATEC (877-425-2832) or at
[email protected].

Akamai Content Control Interfaces. Akamai Confidential. NDA Required for Release. 17
Content Control Utility

18 Akamai Content Control Interfaces. Akamai Confidential. NDA Required for Release.
Chapter 3. Content Control Utility SOAP API

Using CCUAPI • 20
In This Chapter
Using CCUAPI with Perl • 20
Using CCUAPI with Visual Basic • 21
Using CCUAPI with Java and Axis • 22

CCUAPI Reference • 25
Syntax • 25
Function Output • 26
Result Codes and Troubleshooting • 27

The Akamai Content Control Utility SOAP API (CCUAPI) provides a mechanism,
for Akamai customers to write programs that submit a list of cached objects to be
removed from the Akamai network. CCUAPI uses Simple Object Access Protocol
(SOAP) and HTTP or HTTPS as a transport layer.
The CCUAPI uses either the removal-based or the invalidation-based refresh method.
See page 6 for a discussion of the differences between the methods, and see page 25
for information on the options in this API.
Programmers and administrators who use the Content Control Utility SOAP API to
remove content from the Akamai network typically use CCUAPI one of two ways:
• To develop a GUI for developers or those who manage your Web content, rather
than providing many users EdgeControl access.
• To integrate the API into a content management system. For example, you might
want the act of publishing new content to the content management system to
call a function that purges old content from the Akamai network.
For a discussion of best practices—when to use this interface or a different content control
interface, the advantages, disadvantages, and limitations of each, please see the Introduc-
tion to this guide, and in particular the material beginning on page 7.
This chapter provides:
• Guidelines for using CCUAPI and an overview of SOAP.
• A description of CCUAPI, including syntax.
• Instructions for using CCUAPI with Perl, Visual Basic, or Java with Axis.
Examples are provided in a separate zip archive, CCUAPI_examples.zip, available on
control.akamai.com.

Supported The Content Control Utility is available for most objects cached and delivered
Akamai Services through the Akamai network. For streaming services, removal of QuickTime, Real
and Windows Media objects is supported.

Akamai Content Control Interfaces. Akamai Confidential. NDA Required for Release. 19
Content Control Utility SOAP API

Using CCUAPI

Guidelines & Please note the following guidelines for using the CCUAPI:
Limits • Akamai requires the use of HTTPS to maintain security.
• One limit is that files submitted for CCU requests should contain no more than
about 100 URLs of about 400 characters in length. If you receive a “Request
Entity Too Large” error, split your file into smaller files and try again.
• You can submit any number of files containing about 100 URLs, but you should
have no more than 10,000 outstanding requests at any one time. If you receive a
code 332 error, which indicates you have exceeded that limit, you should wait
about 10 minutes and try again.

Setup You must have an EdgeControl user name and password with Content Control Util-
ity permissions. Contact your Account Manager if you do not have this.
1. Download the appropriate WSDL, either from https://ccuapi.akamai.com, or
log in at https://control.akamai.com and go to:
HTTP Content Delivery -> Documentation -> Content Control Utility.
2. Download the CCUAPI Examples files and use the appropriates ones:

If you use.... Download this File

Perl https://ccuapi.akamai.com/ccuapi.wsdl
MS Visual Basic 6, SOAP 1.0 https://ccuapi.akamai.com/ccuapi-list.wsdl
MS Visual Basic 6, SOAP 3.0 https://ccuapi.akamai.com/ccuapi-list-2001.wsdl
MS Visual Basic .Net https://ccuapi.akamai.com/ccuapi-dotnet.wsdl
Java https://ccuapi.akamai.com/ccuapi-axis.wsdl

Note that some SOAP clients download the WSDL file on demand if you specify
this URL when initializing the client.

Using CCUAPI with Perl

Perl-Specific Prior to using CCUAPI with Perl:
Prerequisites
• Visit https://ccuapi.akamai.com/ccuapi.wsdl to download the WSDL file.
• Install Perl 5.005 or greater if Perl is not already installed on the system.
• Download the SOAP toolkit, SOAP::Lite, from http://www.soaplite.com/, and
install it according to its instructions. Ensure that you download the required
Perl packages as specified in the toolkit readme file and install SSL. Downloading
SOAP::Lite without downloading the HTTPS library can result in an infinite
loop.
• Remember to escape special characters from the API, for example, the “@” sign
in the email notification.

20 Akamai Content Control Interfaces. Akamai Confidential. NDA Required for Release.
 Using CCUAPI

UNIX Install SOAP::Lite requires XML::Parser to be installed. XML::Parser requires that you
install Expat on your system prior to installing XML::Parser. SOAP::Lite SSL support
requires that openssl be installed on your system.
A recommended approach to installing the SOAP::Lite and XML::Parser packages is
to use CPAN. For example,
perl –MCPAN –e shell
> install SOAP::Lite
• Download and install ActiveState Perl. A free and simple GUI install program is
available from http://www.activestate.com/.

Using CCUAPI with To use CCUAPI with Perl:

Perl
1. Create a program that allows you to enter a username, password, email address
for notification, as well as a file that contains a list of ARLs/URLs on the com-
mand line. All arguments are required except for email, type, and action. You can
check the usage by typing
perl <program name.>
See the code example, CCURequest.pl, in the separately supplied zip archive
available on control.akamai.com.
2. Run the program, changing the arguments appropriately.
Please download the CCUAPI_examples.zip file for the full details of a Perl example.

Using CCUAPI with Visual Basic

VB-Specific • Install Microsoft’s SOAP client.
Prerequisites • Visit https://ccuapi.akamai.com/ccuapi-list.wsdl to download the appropriate
WSDL file for Visual Basic.

VB Example Please download the CCUAPI_examples.zip file for the full details of this example.
This example presents a form that allows the user to enter a username, password, and
email address for notifications as well as a file that contains a list of ARLs/URLs.
Clicking the Show URLs button displays the ARLs/URLs listed in the data file.
Clicking the Purge URLs button removes objects based on the ARLs/URLs listed in
the data file from the Akamai network.

Creating the Project To create the project, follow the instructions in VBExample.txt from the
CCUAPI_examples.zip archive. You’ll create a new project, add the appropriate text
boxes, buttons, and button methods, and create a new module with provided code.

Running the Program 1. From the Visual Basic menu, choose “Project | References...”, and check
“Microsoft Soap Type Library”.
2. Run the program.
3. Enter your CCU username and password, and the full path/name of the file that
contains the ARL/URL list in the appropriate text boxes.
4. Click Show URLs to verify that you have the correct list.

Akamai Content Control Interfaces. Akamai Confidential. NDA Required for Release. 21
Content Control Utility SOAP API

5. Click Purge URLs to see the result code.

NOTE: If the result is not successful, please see Result Codes and Troubleshooting. For
instance, if you do not have permission to purge the objects you attempted to remove, you
will receive a “Format of URI is invalid” error message. Note that this CCUAPI interface
module defines error code “410” to be a client error.

Specifying an Email You must escape special characters using ASCII codes using the format Chr(<ASCII
Option code>). Specifying an email option within VB code for CCUAPI could look like:
Options(0) = “email” & Chr(45) & “notification” & Chr(58) & “ccuadmin”
& Chr(64) & “examplecontrol.akamai.com” & Chr(46) & “com”

See an ASCII code reference like http://www.ascii.cl for a list of codes.

Using CCUAPI with Java and Axis

This information is meant to provide only an introduction to the usage of the
CCUAPI with Java and Axis 1.3, 1.2 or 1.1. Our customers typically develop their
own applications that use the API. Akamai recommends that you do the same based
on the API specifications.
The following is a detailed procedure on how to install and configure Axis, Xerces,
and the CCURequest commandline client example (tested under Windows, UNIX,
and Cygwin). Please note that the CCUAPI requires all purge requests to be sent over
SSL.

Java-Specific Prerequisites
• The relevant files in CCUAPI_examples.zip ccuapi-axis.wsdl, URLReader.java,
and CCURequest.java. In this example, place these files in ccuapi-axis.
• You must have an EdgeControl user name and password with Content Control
Utility permissions. Contact your Account Manager if you do not have this
access.
• To enable the use of SSL, install the CA root certificate (gte_global_root.der
Windows and gte_global_root.pem for Unix). This is the SSL certificate Akamai
uses for CCUAPI, and these are also found in CCUAPI_examples.zip
• Use JDK 1.4 We recommend installing the Java SDK 1.4 from
"http://java.sun.com/j2ee/1.4/download.html.
• Use a Java SOAP toolkit. This example uses Axis version 1.3, and the setup also
works with Axis 1.2 and 1.1.

Installing Axis & Xerces

If you already have Axis and Xerces installed, skip this set of steps and move on to the
next set of steps.
If you don’t have Axis and Xerces installed, follow these steps:
1. Create a folder or directory into which you will unpack the Axis and Xerces files.
If you're just trying out CCUAPI, make a directory called “ccuapi-axis,” the
name we’ve chosen for this example.

22 Akamai Content Control Interfaces. Akamai Confidential. NDA Required for Release.
 Using CCUAPI

1. Download axis-bin-1_3.zip from the Apache site: http://ws.apache.org/axis/

2. Download Xerces-J-bin.2.7.1.zip from the Apache site:
http://xerces.apache.org/xerces2-j/
3. Unzip the Axis and Xerces .ZIP files into the ccuapi-axis directory.

Setting up the Environment

1. Set the Java CLASSPATH environment variable (in these instructions,
PATH_TO_XXX_DIRECTORY must be replaced with the directory holding the
Axis and Xerces packages).
Note that the CLASSPATH update appends the AXISCLASSPATH to your
CLASSPATH; if you make a mistake, it may be necessary to remove the added
elements and retry. Closing the shell and starting a new one should be sufficient.

In UNIX: export AXIS_HOME="PATH_TO_AXIS_DIRECTORY/axis-1_3"

export XERCES_HOME="PATH_TO_XERCES_DIRECTORY/xerces-2_7_1"
export AXIS_LIB="$AXIS_HOME/lib"
export AXISCLASSPATH="$AXIS_LIB/axis.jar:$AXIS_LIB/commons-discovery-
0.2.jar:$AXIS_LIB/commons-logging-1.0.4.jar:$AXIS_LIB/
jaxrpc.jar:$AXIS_LIB/saaj.jar:$AXIS_LIB/log4j-
1.2.8.jar:$XERCES_HOME/xml-apis.jar:$AXIS_LIB/wsdl4j-
1.5.1.jar:$XERCES_HOME/xercesImpl.jar"
export CLASSPATH="$CLASSPATH:$AXISCLASSPATH"

In Windows: set AXIS_HOME=PATH_TO_AXIS_DIRECTORY\axis-1_3

set XERCES_HOME=PATH_TO_XERCES_DIRECTORY\xerces-2_7_1
set AXIS_LIB=%AXIS_HOME%\lib
set AXISCLASSPATH=%AXIS_LIB%\axis.jar;%AXIS_LIB%\commons-discovery-
0.2.jar;%AXIS_LIB%\commons-logging-
1.0.4.jar;%AXIS_LIB%\jaxrpc.jar;%AXIS_LIB%\saaj.jar;%AXIS_LIB%\log
4j-1.2.8.jar;%XERCES_HOME%\xml-apis.jar;%AXIS_LIB%\wsdl4j-
1.5.1.jar;%XERCES_HOME%\xercesImpl.jar
set CLASSPATH=%CLASSPATH%;%AXISCLASSPATH%

In Cygwin: export AXIS_HOME="PATH_TO_AXIS_DIRECTORY/axis-1_3"

export XERCES_HOME="PATH_TO_XERCES_DIRECTORY/xerces-2_7_1"
export AXIS_LIB="$AXIS_HOME/lib"
export AXISCLASSPATH="$AXIS_LIB/axis.jar;$AXIS_LIB/commons-discovery-
0.2.jar;$AXIS_LIB/commons-logging-1.0.4.jar;$AXIS_LIB/
jaxrpc.jar;$AXIS_LIB/saaj.jar;$AXIS_LIB/log4j-
1.2.8.jar;$XERCES_HOME/xml-apis.jar;$AXIS_LIB/wsdl4j-
1.5.1.jar;$XERCES_HOME/xercesImpl.jar"
export CLASSPATH="$CLASSPATH;$AXISCLASSPATH"
2. Make sure that “java” and “javac” are in your PATH; add the appropriate JDK or
JRE directory, if needed.
3. If you haven’t already done this: from the CCUAPI_examples.zip, unzip the Java
files—CCURequest.java, URLReader.java, and the WSDL, ccuapi-java.wsdl—
into your Axis/Xerces working directory, ccuapi-axis.
4. Generate stubs from “ccuapi-axis.wsdl”:
java org.apache.axis.wsdl.WSDL2Java ccuapi-axis/ccuapi-axis.wsdl
5. Copy the command line client example (CCURequest.java and URLReader.java
from CCUAPI_examples.zip) into “com/akamai/www/purge/”:

Akamai Content Control Interfaces. Akamai Confidential. NDA Required for Release. 23
Content Control Utility SOAP API

cp ccuapi-axis/CCURequest.java com/akamai/www/purge/CCURequest.java
cp ccuapi-axis/URLReader.java com/akamai/www/purge/URLReader.java
Or in Windows:
COPY \ccuapi-axis\CCURequest.java
\com\akamai\www\purge\CCURequest.java
COPY \ccuapi-axis\URLReader.java \com\akamai\www\purge\URLReader.java
6. Compile the commandline client:
javac com/akamai/www/purge/CCURequest.java
com/akamai/www/purge/URLReader.java
com/akamai/www/purge/JavaClasses.java
com/akamai/www/purge/JavaClassesLocator.java
com/akamai/www/purge/PurgeApi.java
com/akamai/www/purge/PurgeApiSOAPBindingStub.java
com/akamai/www/purge/PurgeResult.java

Testing CCUAPI
Put a test URL into a file called “ccuapi.in” and test CCUAPI.

In UNIX: java -cp "$AXISCLASSPATH:." com.akamai.www.purge.CCURequest -user

your_username -pwd your_password -file ccuapi.in

In Windows: java -cp %AXISCLASSPATH%;. com.akamai.www.purge.CCURequest -user

your_username -pwd your_password -file ccuapi.in

In Cygwin: java -cp "$AXISCLASSPATH;." com.akamai.www.purge.CCURequest -user

your_username -pwd your_password -file ccuapi.in

CP Code Example The above examples are to purge a specific URL. This Windows example is for a
refresh using a CP Code. Only administrative level users can purge by CP Code; this
type of purge can be inefficient and use extensive resources.
java -cp %AXISCLASSPATH%;. com.akamai.www.purge.CCURequest -user
your_username -pwd your_password -type cpcode -file ccuapi.in

SSL Problem? You should see a success message. If you have SSL negotiation problems, you may
Is Cert Installed? need install the GTE root CA certificate into your Java runtime's cacerts file. This
should not be necessary with JDK 1.4, which ships with this certificate CA prein-
stalled. The command will look like this for UNIX
keytool -import -trustcacerts -keystore $JAVA_HOME/jre/lib/security/
cacerts -file CCUAPI_examples/gte_global_root.pem

Or in Windows:
keytool -import -trustcacerts -keystore
%JAVA_HOME%\jre\lib\security\cacerts -file CCUAPI-
axis\gte_global_root.der

The default passphrase from the Java distribution is “changeit.” After adding the CA
certificate, retry the test.

24 Akamai Content Control Interfaces. Akamai Confidential. NDA Required for Release.
 CCUAPI Reference

CCUAPI Reference
The following sections describe the syntax and elements of CCUAPI.

Syntax This syntax example that assigns the output of the function called purgeRequest to
the variable result:
PurgeResult result =purgeRequest(user, pwd, network, options[],uri[])

Function Detail The function PurgeRequest takes the following parameters:

Parameter Description

user Username for https://control.akamai.com; case sensitive.

pwd Password for https://control.akamai.com; case sensitive.

network Deprecated; this parameter is ignored by CCUAPI. Use the empty string
("") as a value for this parameter.

options Array of options: action, domain, email-notification, or type.

Case insensitive. If you use multiple options (for example, action and
email-notification, put each option in a separate element of the array.
You should include any option you want to set.

action Specify whether the object should be removed from cache, resulting in a
full GET request to origin, or invalidated, resulting in an IMS GET request.
The syntax is:
action=remove
action=invalidate

domain Specify the network: remove from staging (Edge Staging Net-
work, or ESN) or production (the default). The syntax is:
domain=production
domain=staging

email- Specify email addresses for completed removal notifications:

notification email-notification [email protected]
To send notification to multiple email addresses, the 'options' argument
must be formatted to contain a comma-separated list of email addresses:
[email protected],[email protected]
NOTE: Remember to escape the “@” sign and all other special charac-
ters if necessary.

type Specify whether the strings in the uri array are ARLs/URLs representing
individual objects, or if they are CP codes that should be interpreted as
requests to purge all content associated with that CP code. The syntax is:
type=arl
type=cpcode
NOTE: To use the type cpcode option, your administrator must enable
purge-by-cpcode access for your username through Akamai EdgeCon-
trol.

Akamai Content Control Interfaces. Akamai Confidential. NDA Required for Release. 25
Content Control Utility SOAP API

Parameter Description

uri An array of ARLs/URLs to be purged from the network, or an array of CP

codes, depending on what was specified in the parameter options.
Case sensitive.

NOTE: All members of this array must of the same type, either all ARLs/
URLs, or all CP codes. Wildcards are not supported. You must fully spec-
ify the ARLs/URLs to be purged.

Note: If you are using Perl with SOAP::Lite and using the option type
cpcode, you may have to include a space before the CP code value so
that SOAP::Lite sends it as a string. For example:
purgeRequest("username", "password", "", [
"type=cpcode", "action=invalidate" ] , [ " 555" ]);

ARL/URL Examples:
Standard Akamai edge server configuration:
http://www.example.com/logo.gif

FreeFlow:
http://a9.g.akamai.net/7/2/3/4/www.example.com/
logo.gif

Function Output The elements in the PurgeRequest structure include the following:r

Element Type Description

resultCode Int Indicates success or failure of removal request.

resultMsg String Explains result code

sessionID String Unique ID assigned to the removal request.

estTime Int Indicates the estimated time for the request to be pro-
cessed, in seconds. A value of -1 indicates that there is no
estimated time, usually appearing when the request fails.

uriIndex Int If the request fails because of a bad ARL/URL, this identi-
fies the index of the first failed ARL/URL in the array. A
value of -1 indicates there were no bad ARLs/URLs, or that
an error occurred before the ARLs/URLs were parsed.

Sample Output Output from the content removal request can look like the following:
resultCode: 100; resultMsg: Success; sessionID: 29361; estTime: 540;
uriIndex: -1;

When this function returns, it indicates that your purge request is put in the queue,
to be processed by the Akamai network. A notification at the email you specified
indicates that the content has been removed from the network.
The resultCode elements are defined in the next section.

26 Akamai Content Control Interfaces. Akamai Confidential. NDA Required for Release.
 CCUAPI Reference

Result Codes and Troubleshooting

This section provides an overview of CCUAPI result codes, as well as their definitions
and the steps you can take to correct the issues.
If you need further assistance, call your Akamai Integration Consultant, or contact
Customer Care at 877-4-AKATEC (877-425-2832) or [email protected].
Result codes are patterned as follows:
1xx Text Message

Code Element Indicates

1xx Successful Request

2xx Warning; reserved. The removal request has been accepted.

3xx Bad or invalid request.

4xx Contact Akamai Customer Care.

The follow table outlines specific result codes that you may encounter while making a
purge request and provides troubleshooting information for codes that correspond to
failed requests. Additional result codes might be added as necessary.

Code indicates Troubleshoot

301 Invalid username or Your Akamai portal username & password must have a
password tech or admin role and the appropriate contract associ-
ation. Contact your Akamai Account Manager if you
believe your login information is inaccurate.

302 Bad syntax for an

option.

303 Invalid value for an To send notification to multiple email addresses, the
option. 'options' argument must be formatted to contain a
comma-separated list of email addresses:
[email protected],user2@exam-
ple.com

Formatting as follows does not work: email-notifica-

[email protected] email-notifica-
[email protected]
NOTE: Users must remember to escape the “@” sign
and all other special characters if necessary.

304 Option already pro- Multiple email notification addresses are formatted
vided. incorrectly.

320 URI provided Make sure that the ARLs/URLs to be removed are spec-
ified in the request.

321 Format of ARL/URL is Make sure each string has only one ARL/URL. ARLs/
invalid URLs using streaming protocols are not currently sup-
ported.

Akamai Content Control Interfaces. Akamai Confidential. NDA Required for Release. 27
Content Control Utility SOAP API

Code indicates Troubleshoot

322 You are not autho- CCU compares you URI requests to your CP code and
rized to purge this domain. You can only request removals of domains
ARL/URL associated with your CP code. Contact your Account
Manager for further assistance.

323 ARL/URL illegal CCU compares you URI requests to your CP code and
domain. You can only request removals of domains
associated with your CP code. Contact your Account
Manager for further assistance.

332 Maximum number of No more than 10,000 ARLs/URLs can be pending at

ARL/URLs in out- any given time. If you receive errors, wait about 10
standing purge minutes and try again.
requests exceeded

401, 402 Error Contact Akamai Customer Care at 877-AKATEC (877-

425-2832) or [email protected].

The “Request Entity Too Large” (413) Error

This error comes from a source other than the CCUAPI-code based errors above. If
you receive this error, you have exceeded the file-limit for the submission. There is a
limit to the file size submission of about 100 URLs of about 400 characters in length.
If you receive this error, split your request up into multiple smaller requests and try
again.

28 Akamai Content Control Interfaces. Akamai Confidential. NDA Required for Release.
Chapter 4. Enhanced Content Control Utility

Before You Begin • 29

In This Chapter
Using the ECCU • 30
Viewing Previous Refresh Requests • 32

About the Data Fields • 33

ECCU Status Messages • 34

The Enhanced Content Control Utility (ECCU) is a GUI available on Akamai Edge-
Control, https://control.akamai.com that allows you to specify the refreshing of
cached objects through two ways:
• You can use rules involving path and extensions that could be summarized as,
“Refresh objects with this extension in this path.”
• You can upload ECCU files, enabling you to specify more complex rules by
which objects will be refreshed—not only path or extension, but also using crite-
ria such as the contents of requests, cookies, CP codes, or other criteria.
The Enhanced CCU uses an invalidation-based refresh method. That is, once it
receives the refresh instructions, the cached instance is marked as invalid. The Aka-
mai server receiving a client request for objects matching the particular path and
extensions sends an If-Modified-Since—a conditional GET—to the origin. If it finds
a newer version at the origin, it removes the existing cached instance and replaces it
with the newer version fetched from the origin.

Before You • The ECCU applies to content configured for control with edge server configura-
Begin tion files. If your content does not use a configuration file, use the CCU.
• You’ll need to have access to https://control.akamai.com. If you don’t have access
to this Content Control Utility, check with your Akamai representative.
• Familiarize yourself with how this tool works, as discussed in subsequent sec-
tions. The specific kind of path and extension formulations may be new to many.
For a discussion of best practices—when to use this interface or a different content control
interface, the advantages, disadvantages, and limitations of each, please see the Introduc-
tion to this guide, and in particular the material beginning on page 7.

Before You Upload ECCU Files

You’ll need to be familiar with Digital Properties (page 37) and with the ECCU file
structure and options (page 39).

Akamai Content Control Interfaces. Akamai Confidential. NDA Required for Release. 29
Enhanced Content Control Utility

Using the ECCU

To use the ECCU:
1. Log in to control.akamai.com.
2. In the sidebar, click the product link for the product you want to work on.
3. Under the product, click the Content Control Utility link.
The Content Control Utility Content page contains both the CCU (Refresh by
URL) and ECCU applications (Refresh by Directory and File Extension). The
CCU page (shown in Figure 1 on page 12) is the default.
4. Click the Refresh by Directory & File Extension link to view the ECCU page.

Figure 3. The Content Control Utility Link on the Manage tab page.

See page 33 for definitions of the data you see on this page. For information on the
Digital Property and ECCU file structure, see pages 37 and 39, respectively.
5. Select the Digital Property Name(s) and, optionally, give this request a name to
identify it in the future.

30 Akamai Content Control Interfaces. Akamai Confidential. NDA Required for Release.
 Using the ECCU

6. Choose the refresh method:

- Refresh all files in a directory
- Refresh by directory and extension
- Upload an ECCU file containing the refresh instructions.

Figure 4. Selecting the files to refresh

7. When you’re ready, click the Next button to go to a confirmation page on which
you can review your submission before finalizing it.
8. On the confirmation page, review your data and when ready, click the Submit
Request button.
The Metadata you see on the confirmation page is the ECCU file, the encoded
refresh rules, which is described on page 39.
9. The successful submission takes you to the Request Submitted page, where you
should note the displayed Request ID that can be used for tracking and problem
solving. If you want, click Refresh Content to return to the ECCU main page.

Akamai Content Control Interfaces. Akamai Confidential. NDA Required for Release. 31
Enhanced Content Control Utility

Viewing Previous Refresh Requests

To view previous requests and their associated metadata:
On the Refresh Content page (see Figure 4 on page 31) click the View Previous
Refresh Requests link to view a table of previous requests.

Figure 5. Viewing Previous Refresh Requests

In this table, you can click View Details to view more data, including the metadata
code for the file, which is described on 39. The Status messages are described on page
34. You can also use the display options at the bottom to sort the table or change the
number of files displayed.

Resubmitting a To resubmit a request displayed in the list of previously submitted requests, click the
Request Resubmit link for the request, then on the next page, confirm by clicking the Submit
Request button.

32 Akamai Content Control Interfaces. Akamai Confidential. NDA Required for Release.
 About the Data Fields

About the Data Fields

When you enter the refresh instructions (Figure 4), you use the following data:
• Name (optional)
The Name is for your convenience should you later want to refresh content using
the same criteria. It’s a note to yourself or your co-workers. For example, “logo
images cleanup” or “test directories cleanup.”
• Digital Property Name, Type, and Match (presence or absence of “*”)
Select the Digital Property Name(s) you want to work on. You can select up to
20 names.
The Property Type (ARL Token or Host Header) is at the right of the name.
If the property is an inexact match, it is preceded by a wildcard asterisk, as in
“*.example.com”. Exact matches show no wildcard, as in “www.example.com”.
The digital property name, type, and match, are described in “About Digital
Properties” on page 37.
• Directory
- To specify the root directory, use “/” by itself, and in any case, the path
should start with a “/”. Note that if the match is inexact, the match is for any
root directory matching the property name. For example, if the property is
*.example.com, and you use / for the directory, you’re giving instructions to
refresh everything under test.example.com/, www2.example.com,
another.example.com/, and so forth. However, this would not match new-
example.com.
- When you specify a directory, its subdirectories are automatically included.
- Don’t use wildcard characters (? *), dots (.), commas (,) or semi-colons (;).
• Files to Refresh
You can choose to refresh all files in the directory, or you can specify the file
extensions to refresh. If you choose to refresh by extension:
- Don’t use dots, wildcard characters, commas or semi-colons (. * ? , ;) in the
extensions. That is, “gif ” is OK, but the following are NOT OK: “.gif ”,
“htm*” or “htm?”.
- Case doesn’t matter: “GIF” is the same as “gif ”.
- To enter a number of extensions, separate each by a space, for example, “gif
jpeg jpg html htm tiff tif.”
• Use the Following ECCU Files
See information on the Digital Property and ECCU file structure, on pages 37
and 39, respectively.
• Email (optional)
If you want email notification when the request is processed, enter the email
address you want notified.

Akamai Content Control Interfaces. Akamai Confidential. NDA Required for Release. 33
Enhanced Content Control Utility

ECCU Status Messages

In the list of most recent refresh requests, the right-most column shows whether the
request is pending, has completed successfully, or has failed. If you click the View
Details link, you’ll see more complete status messages.

Informational The possible informational messages you’ll see are:

Messages • File uploaded and awaiting processing
• File successfully transferred to the validation server, and waiting for validation
• File successfully validated and waiting for deployment to Akamai's network
• File successfully deployed to Akamai's network
• File obsoleted by the validation server since a newer version is available
With the exception of the last message, the “obsolete” message, these messages simply
indicate the stages in the successful implementation of your instructions.
For the “File obsoleted” message, no action is necessary. This message indicates you
have submitted new instructions that make the old ones invalid.

Error Messages The possible error messages you’ll see are:

• File transfer to the validation server has failed
• File Invalid (Internal Error)
• Error during deployment to Akamai's network
These messages indicate that your refresh instructions have not been deployed, and
they are accompanied by extended messages describing the specific error.
If you want the refresh to occur, you’ll need to fix whatever caused the error. Contact
Customer Care if you need help.

34 Akamai Content Control Interfaces. Akamai Confidential. NDA Required for Release.
Chapter 5. ECCU Publisher (PublishECCU)

The ECCU Publisher (PublishECCU) is an EdgeControl Web Service, a SOAP API.

EdgeControl Web Services allow you to access many EdgeControl services using a
SOAP-based interface instead of a browser.
Web services use the same access and permissions, and the same user names and pass-
words, that you would use to access Akamai EdgeControl by browser. Your SOAP cli-
ent uses HTTP Basic Authentication to transmit the user name and password in the
SOAP request.
Akamai provides the Web Services Description Language (WSDL) files to use in your
SOAP-based interface and sample code to create HTTP Basic Authentication access
to the services.

ECCU Publisher The PublishECCU API provides methods to upload ECCU files to the Akamai net-
work, view and modify attributes of previously uploaded files, or delete these files.
ECCU (Enhanced Content Control Utility) file structure is used to specify files to
refresh on the Akamai network using path criteria such as the directories or exten-
sions, or using certain HTTP request or response properties.
When you use ECCU files, you work with the ECCU structure and syntax, and you
work with the Digital Property. The ECCU file and digital properties are described in
other chapters in this document.
For a discussion of best practices—when to use this interface or a different content control
interface, the advantages, disadvantages, and limitations of each, please see the Introduc-
tion to this guide, and in particular the material beginning on page 7. ECCU File best
practices are described on page page 42.

Akamai Content Control Interfaces. Akamai Confidential. NDA Required for Release. 35
ECCU Publisher (PublishECCU)

36 Akamai Content Control Interfaces. Akamai Confidential. NDA Required for Release.
Chapter 6. About Digital Properties

Many Web Services as well as browser-based upload functions on Akamai EdgeCon-

trol require the use of digital properties. For example, you use digital properties when
you when you work with ECCU files or with WAR files in the EdgeComputing envi-
ronment. The digital property identifies the hosts you’re working with, its name and
type.

The PropertyName, Type, and Exact / Inexact Match

In the Web interfaces, you’ll see data entry for Digital Property Name and Type.
Normally, these are described together—for example, example.com (ARL Token) or
example.com (Host Header), are names followed by types in parentheses.
In the Web Services SOAP APIs, you’ll see fields such as propertyName or proper-
tyNameExactMatch

Digital Property Attributes Configured in Setup, Not in These Interfaces

The following material describes these data in more detail. It is important to note
that these values are set when Akamai configuration for your site is set up; the names
are not necessarily the same as your origin name, and they cannot be set or changed
in these interfaces. You can view your property names and associated attributes in the
Enhanced Content Control Utility or ECCU file upload interface on the control.aka-
mai.com management center, as described elsewhere in this document. If you have
questions, check with your Akamai representative.

The Digital Property A digital property, defined by its name, type, and whether it is an exact match, iden-
and the ARL tifies the set of objects you’re working on, and to understand what it is, you need first
to understand the ARL.
The ARL (Akamai Resource Location) is similar to the URL, the difference being
that the ARL is specifically defined for objects to be served via the Akamai network.
There are two types of ARLs:
• The v1 ARL
This is the original ARL used in the Akamai Freeflow Network, and it contains
data coded into its structure. Such an ARL might look like this:
http://a123.g.akamai.net/7/123/456/e358f5de00e9/www.example.com/logo.gif
The “example.com”—the portion that looks like a host name, is the ARL Token,
a digital property type that is further discussed in the next subsection. It is a token
because it refers to a hostname but is not necessarily in the form of a host name.

Akamai Content Control Interfaces. Akamai Confidential. NDA Required for Release. 37
About Digital Properties

• The v2 ARL
On Akamai edge servers, configuration files provide extensive content control.
The properties previously specified in the v1 ARL, along with many other prop-
erties, are defined in these files. The v2 ARL resembles a common URL:
http://www.example.com/logo.gif
The “example.com” is called a Host Header, the other digital property type. Sim-
ply, it is in the hostname that appears in the “Host:” header sent by the client
browser; thus, Host Header.

The Property Name and Types—Host Header or ARL Token

The “example.com” in the above ARLs is the property name, and it is either of the
type Host Header or ARL Token, depending on the ARL type, v1 or v2, with which it
is associated.
The type then tells the Akamai network whether content control information is con-
tained in the ARL, or whether all such information is contained in a configuration
file. When you work with ECCU files, you’ll need to know the type.
Exact Match or RHS? Other than name and type, the attribute associated with the property is whether it is
an exact or inexact (RHS, or Right Hand Side) match.
• With an exact match, “example.com” would not match “test.example.com” or
other subdomains of example.com.
• With an inexact, or RHS match, “example.com” matches “test.example.com” and
other subdomains. The RHS match does not include “example.com.au” or
“example.co.uk,” nor would it include “anotherexample.com.”

The Digital Property May Represent Many Hostnames

The preceding paragraphs on exact vs. inexact match touched on this, but to be
explicit: you digital properties can represent many hostnames.
For example, if your digital property is “example.com” it can represent several subdo-
mains—www.example.com, www2.example.com, good.example.com, bad.exam-
ple.com, unclear.example.com.
To Limit an ECCU Refresh Request to Certain Hostnames
A request to refresh content on the digital property “example.com” will cause the con-
tent to be refreshed for all of these hostnames. To limit the invalidation to a particular
hostname, you should use the criteria of matching the request header match on the
Host: header, and this can be done only on a Host Header property type.

38 Akamai Content Control Interfaces. Akamai Confidential. NDA Required for Release.
Chapter 7. Enhanced CCU Request Format

Format of an Enhanced CCU Request • 39

In This Chapter
Rules for Proper Syntax • 40
Revalidation Examples • 40

The Revalidate Tag • 43

Match Tags • 44
Summary of Matches Used to Revalidate Content • 45
Path Matches • 46
Request Property Matches • 49
Response Property Matches • 57

This chapter describes the format of the Enhanced CCU request file and the meta-
data tags that can be used to define a refresh, or revalidate, request.
You can submit an Enhanced CCU request file to Akamai through ECCU file upload
using the Enhanced Content Control Utility (ECCU) Web interface on the manage-
ment center, or through the ECCU Publisher web service. The ECCU structure is
also used directly with the ECCU Web interface, but requests made using the GUI
are limited to path and extension matches. You can also view the resulting ECCU
data in that interface.
For a discussion of best practices—when to use this interface or a different content control
interface, the advantages, disadvantages, and limitations of each, please see the Introduc-
tion to this guide, and in particular the material beginning on page 7.

Format of an Enhanced CCU Request

An Enhanced CCU file is a straight text file in a simplified XML format. The tags
available in the file are:
• <eccu> </eccu> as opening and closing tags to indicate the type of the file.
• <match> tags to define the URI for the object or some other attributes by which
to identify the objects to be revalidated.
• <revalidate> to specify a timestamp value. Objects with older timestamps must
be revalidated before they are served.
In simplified form the file would look like this.
<eccu>
<match:tagname value=”value”>
<revalidate>epochtime | now </revalidate>
</match:tagname>
</eccu>

Akamai Content Control Interfaces. Akamai Confidential. NDA Required for Release. 39
Enhanced CCU Request Format

The following is a practical example of an Enhanced CCU file that purges the object
referenced by the following URL/path:
http://www.example.com/products/images/*.gif, *.jpg

<eccu>
<match:recursive-dirs value=”products”>
<match:recursive-dirs value=”images”>
<match:ext value=”gif jpg”>
<revalidate>1046581729</revalidate>
</match:filename>
</match:recursive-dirs>
</match:recursive-dirs>
</eccu>

Note that this general invalidation (that is, all files under the images subdirectory
with gif and jpg extensions, as opposed to specifying specific files) is the kind of
refresh that the Enhanced CCU is designed to provide.

Rules for Proper Syntax

The following rules are essential to producing syntactically correct refresh/revalida-
tion requests:
• The file must start and close with the <eccu></eccu> tags.
• Tag names and content strings are case-sensitive. Tag names must use lower-case
throughout, and the match tag value is matched in a case-sensitive manner.
• Files can contain multiple revalidate tags. However, you cannot have two identi-
cal matches at any level in the tree. See the example on page 43.

Revalidation Examples
This section shows some example Enhanced CCU requests—it is not complete or
exhaustive but is meant to be representative. It is followed by examples of Best Prac-
tices in requests (page 42).

Based on the Digital You can invalidate all content associated with a Digital Property by submitting a
Property request file that contains only the revalidate tag.
<eccu>
<revalidate>1046581729</revalidate>
</eccu>

The Digital Property to which this request applies is described in the chapter, “About
Digital Properties” on page 37. Note that a Digital Property may encompass many
hostnames.
Caution: A request over an entire digital property may cause a great deal of content
revalidation and thus may cause a greatly increased request load on origin server. You
should use this type of request only if you intend to revalidate all content served
under a particular Digital Property.

40 Akamai Content Control Interfaces. Akamai Confidential. NDA Required for Release.
 Format of an Enhanced CCU Request

Based on Host A Digital Property may encompass many possible hostnames (for example, the Digi-
Header tal Property *.example.com would include images.example.com, www.example.com,
any.example.com). Often it is more practical to restrict the revalidation to a particular
hostname by enclosing the revalidate tag in a match on the Host header in the
request. This request causes all requests from www.example.com to be revalidated.
<eccu>
<match:request-header operation="name-value-cmp" argument1="Host"
argument2="www.example.com">
<revalidate>now</revalidate>
</match:request-header>
</eccu>

Since the request-header match allows for substring comparisons on the value of the
header, you could expand this request to revalidate all content served from any sub-
domain of example.com.
<eccu>
<match:request-header operation="name-value-strstr" argument1="Host"
argument2=".example.com">
<revalidate>1046581729</revalidate>
</match:request-header>
</eccu>

Based on Directory You might wish to invalidate only the content served from a particular directory
Structure under a particular hostname. For example, you might want to invalidate all content
served from the “dailyspecials” directory of www.example.com.
<eccu>
<match:recursive-dirs value="dailyspecials">
<match:request-header operation="name-value-cmp" argument1="Host"
argument2="www.example.com">
<revalidate>1046581729</revalidate>
</match:request-header>
</match:recursive-dirs>
</eccu>

The instructions above cause all of the files in the “dailyspecials” directory and its
subdirectories to be revalidated.
Path Matches Cannot be Nested
Path matches cannot be enclosed in other match types. You’ll notice in the example
above that the request-header match is enclosed inside the directory match, even
though you might consider the hostname of a request to be more general than the
directory (or, in this sense, the URL path component). However, you can use multi-
ple matches in a single request (see page 42).

Based On File If the entire web site has been republished, you might want to force revalidation of a
Extension large number of files. For example, you might want to revalidate all files with the
extension .html. This could be accomplished with a single match on the extension:
<eccu>
<match:ext value=”html”>
<revalidate>now</revalidate>
</match:ext>
</eccu>

Akamai Content Control Interfaces. Akamai Confidential. NDA Required for Release. 41
Enhanced CCU Request Format

Best Practices in Requests: Use Space-Separated Values

The number of ECCU revalidate requests that can be included in the configuration
for a single host header is limited to keep the invalidations from piling up endlessly.
Submitting more than 250 invalidation requests at one time can result in a “global
invalidation” –revalidating all content for that host header.
The way to avoid this is to invalidate multiple objects or paths in one request. You do
this by using multiple, space-separated values for matches. Since each value is evalu-
ated separately in only one request, this is a more effective way to submit requests.
Here’s an example match using multiple values separated by spaces.
The Right Way
<match:recursive-dirs value="dir_1 dir_2 dir_3">
<revalidate>now</revalidate>
</match:recursive-dirs>

This is more efficient and a much better practice than creating three matches that
look like this:
The Wrong Way
<match:recursive-dirs value="dir_1">
<revalidate>now</revalidate>
</match:recursive-dirs>

<match:recursive-dirs value="dir_2">
<revalidate>now</revalidate>
</match:recursive-dirs>

<match:recursive-dirs value="dir_3">
<revalidate>now</revalidate>
</match:recursive-dirs>

Multiple Levels, Multiple matches can be applied to multiple levels. For example, to invalidate a “end-
Multiple Matches point name” in multiple trees, enclose the intermediate names in a single match. This
is valid:
<match:recursive-dirs value="top_dir">
<match:recursive-dirs value="mid_dir_1 mid_dir_2 mid_dir_3">
<match:recursive-dirs value="end_dir">
<revalidate>now</revalidate>
</match:recursive-dirs>
</match:recursive-dirs>
</match:recursive-dirs

This one request would replace 12 individually built requests:

<match:recursive-dirs value="top_dir">
<match:recursive-dirs value="mid_dir_1 mid_dir_2 mid_dir_3">
<match:recursive-dirs value="end_dir_1 end_dir_2 end_dir_3 end_dir_4">
<revalidate>now</revalidate>
</match:recursive-dirs>
</match:recursive-dirs>
</match:recursive-dirs

42 Akamai Content Control Interfaces. Akamai Confidential. NDA Required for Release.
 The Revalidate Tag

The Revalidate Tag

The <revalidate> tag indicates a timestamp after which any content in cache with
an older timestamp will be considered stale. The timestamp in the tag is normally the
current time, to effect a revalidation on the next request from “now” and thus ensure
that every edge server will revalidate its copy of the file.
The timestamp may be a time in the past, though it should never be a time before the
content was last changed on the origin server. Otherwise, old versions of the content
may persist in cache. The tag has the following syntax:
<revalidate>1113551040</revalidate>
<revalidate>now</revalidate>

The content of the tag may be:

• The key word, now, telling the system to process the request as soon as possible,
with now meaning the time that Akamai receives the request.
• An integer representing an epoch time. In the above example, the 1113551040
statement means, “revalidate the file with an If-Modified-Since request to the
origin if it was last validated before “Fri Apr 15 07:44:00 2005 UTC.”

Using Multiple Files can contain multiple revalidate tags. However, you cannot have two identical
Revalidate Tags matches at any level in the tree.
For example, the following is invalid because the match on foo valley” appears
twice at the same level:
<match:foo value="a">
<match:bar value="b">
<revalidate>now</revalidate>
</match:bar>
</match:foo>
<match:foo value="a">
<match:bar value="c">
<revalidate>now</revalidate>
</match:bar>
</match:foo>

The valid form of the above statement removes the duplication:

<match:foo value="a">
<match:bar value="b">
<revalidate>now</revalidate>
</match:bar>
<match:bar value="c">
<revalidate>now</revalidate>
</match:bar>
</match:foo>

About Epoch Time The time for the <revalidate> tag is in Unix “epoch time” format. This time is the
number of seconds that have passed since 1 January 1970 00:00 UTC. You can find
the current epoch time with the following Unix command:
$ date +%s

Akamai Content Control Interfaces. Akamai Confidential. NDA Required for Release. 43
Enhanced CCU Request Format

1010705782

You can print the Unix epoch time of a particular time string as follows. (Note the
example uses a very special date in the Pacific time zone corresponding to the epoch
time with “nine nines”.)
$ date -d 'Sat Sep 8 18:46:39 PDT 2001' +%s
999999999

That same epoch time in a different time zone:

$ date -d 'Sun Sep 9 01:46:39 UTC 2001' +%s
999999999

So you can specify the time in any time zone and it will be the same on every Unix
machine (provided their date setting is correct). Unix has done the conversion from
your time zone to UTC for you.
However, for clarity it's always best to express times in GMT or UTC, since this is
the time zone used by Akamai servers and it avoids errors due to time zone conver-
sion and daylight-saving-time changes.

Match Tags
There are three types of matching you can perform in an Enhanced CCU request:
Path matching is used to describe the URL path
Request property matching is used to identify the request by some attribute
other than its URL. Commonly used properties of requests include: query string
arguments, file extensions, method (POST or GET)
Response property matching is used to identify the request by some attribute in
the response from the origin server. In this case, there is only one match type
available: response-header.
The table on the next page summarizes the available matches, and it is followed by an
extensive discussion of the matches and how they are used.

44 Akamai Content Control Interfaces. Akamai Confidential. NDA Required for Release.
 Match Tags

Summary of Matches Used to Revalidate Content

Type Tag Usage
URL Path recursive-dirs Match on the URL path components by name. Lets you invalidate all URLs that begin
with a particular directory structure. Can nest only inside path matches.
sub-dirs-only Match on all subdirectories of a given directory. Treats the directory name like ‘*’, as in:
/named-dir/*/named-dir/filename.ext
Can nest only inside path matches.
this-dir Constrains the invalidation to the current directory. Otherwise it would apply to all sub-
directories of the given directory.
Can nest only inside path matches.
filename See Caution belowa. Matches on the exact filename, nests only inside path matches.
Request ext Matches on the given file extensions. You can list multiple extensions and it is recursive,
Property so that a single match will apply to all files with the given extension in all directories
unless you nest this inside a URL path match.
cookie See Caution belowa. Matches on the cookie name or name and value. Useful if the
site caches responses separately based on the presence of a cookie. For example, a
cookie that identifies the language of the end client might be used to separate English
content from French content in cache. Using this match, you would be able to invali-
date one set of content without invalidating the other set.
cpcode-range Matches a CP-code or range of codes. Useful if the site uses multiple CP-codes to segre-
gate content.
arl-type Matches on the type of the ARL (edge server configuration or FreeFlow).
request-header See Caution belowa. Matches on the name or name and value of the header. Useful
for matching on the Host: in the request if many hostnames are served from a single
origin site and the contents are cached separately based on hostname. This is useful
when a client header is included in the Cache Key using the Force CacheID feature.
request-type Matches on the source of the request (end user versus ESI processor, for example.) This
is not generally a useful distinction for invalidations.
method Matches on the method of the request. Method is a component of the cache key by
default. This is useful if POST responses are being cached and you want to distinguish
between POST and GET in your invalidation request.
protocol Matches on the protocol (HTTP vs. HTTPS). Protocol is a component of the cache key by
default, so this match is useful for invalidating one set of content but not the other.
query-string See Caution belowa. Matches on the name or name and value of a query string argu-
ment. Useful if query arguments are being used to distinguish objects in cache by
including the arguments in the cache key.
typecode Matches on the typecode of the request v1 ARL. May be useful if you want to invalidate
FreeFlow request objects that use a particular typecode. For example, all requests that
use an Object ID under typecode 7.
response response- See Caution belowa. Matches on header name or name and value. Useful if a custom
property header identifier is used to tag content. It is then possible to invalidate the content that con-
tains the custom identifier rather than identify the content by other properties.

a. Use these matches with caution! You can create a large number of unique matches and thus build a
large purge.data file and adversely affect site performance. See the discussion, “ECCU Limitations” on
page 8.

Akamai Content Control Interfaces. Akamai Confidential. NDA Required for Release. 45
Enhanced CCU Request Format

Path Matches The <match> tags listed in this section are used to describe the URL path. These tags
are sometimes referred to as URL component matches. They create “nodes” in the
metadata file and assist in the efficient application of metadata to requests.
The path match tags and their meanings, which are discussed in detail in the subse-
quent section of this chapter, are:
recursive-dirs value="path component": match the specified directory and all its
suddirectories
sub-dirs-only: match all directories nested within the current directory, but not
the current directory
this-dir: match the current directory, but not its subdirectories
filename value="filename.ext": match an exact file within the current directory
filename value="No File Specified": match the default file within the current
directory
URL Components Must be Nested with Each Other and not with Other Match Types
You cannot nest URL component matches within any other match type. That is,
these matches are used to describe the URL and must be nested within one another in
an unbroken fashion to form the URL path in its proper order. For example, you can-
not nest a “recursive-dirs” match inside a “cookie” match, because the cookie is not a
component of the URL. And you must list the components in the correct order, so
you cannot enclose a “recursive-dirs” match within a “filename” match, because the
filename is always last in the URL.

Wildcards and Regular Expressions Are Not Supported

There is currently no support for wildcards (for example, *) or regular expression
matching syntax in path matches. However, see the sub-dirs-only match, for a special
case of declaring a path indirectly.

recursive-dirs The recursive-dirs match is used to match against a particular path component
(directory) and any subdirectories of that path component. If you don’t want to
match recursively, you would pair this match with a this-dir match, as explained
below. The syntax for this path match is:
<match:recursive-dirs value="dir" nocase="off" include-path-params="off">
</match:recursive-dirs>

The value attribute is the directory name without the leading or following slash (/).
The nocase attribute is a Boolean to specify whether or not the match should be
case-sensitive. A setting of “on” makes the match case-insensitive. The default is “off.”
The “include-path-params” attribute is a Boolean to specify whether path param-
eters should be considered when matching on a path component. By default, the flag
is off and the path parameters are ignored during the comparison.
Notice that the match is for a single component of the URI path. You must not com-
bine path components to match a longer portion of the URI path.

46 Akamai Content Control Interfaces. Akamai Confidential. NDA Required for Release.
 Match Tags

That is, the following syntax is not allowed:

<match:recursive-dirs value="images/borders">

Although the match value is a single component of the URI path, this does not mean
that the component can exist anywhere in the URI and result in a match. A more
complete metadata example would look something like this:
<eccu>
<match:recursive-dirs value="images">
<revalidate>1046581729</revalidate>
</match:recursive-dirs>
<eccu>
...

In the example above the match tag <match:recursive-dirs value="images"> is

at the root directory. This match applies to any files that match the URI paths:
www.example.com/images/
www.example.com/images/*/
www.example.com/images/*/*/...

Note that it does not apply the revalidate metadata to:

www.example.com/electronics/images/

The metadata example could be expanded to include another subdirectory, which

would be specified with a separate tag. The relevant portion of the metadata would
look like the following:
<match:recursive-dirs value="images">
<match:recursive-dirs value="borders">
<revalidate>1046581729</revalidate>
</match:recursive-dirs>
</match:recursive-dirs>

The example above applies the <revalidate> tag to all files that match the URI path:
www.example.com/images/borders/
www.example.com/images/borders/*/...

sub-dirs-only The syntax for this path match is:

<match:sub-dirs-only value="Sub-directories Only">
</match:sub-dirs-only>

This match is used to set metadata for all directories beneath the current directory,
but not the current directory. In most cases you will first declare the directory in a
separate recursive-dirs match. The exception is when you mean to match on any
directory below the root directory.
The following metadata example sets revalidation for all files in any subdirectory of
the “images” directory, but not the images directory itself.
<match:recursive-dirs name="images">
<match:sub-dirs-only" value="Sub-directories Only>
<revalidate>1046581729</revalidate>
</match:recursive-dirs>
</match:recursive-dirs>

Akamai Content Control Interfaces. Akamai Confidential. NDA Required for Release. 47
Enhanced CCU Request Format

Nesting sub-dirs-only Matches

It is also possible, though not recommended, to nest sub-dirs-only tags within each
other to specify a path that contains no specific component names.
Specifically, you could match any files in directories three levels deep and below, such
as these:
www.example.com/anydir/anydir2/anydir3/
www.example.com/images/borders/specials/

and apply <revalidate> with the following metadata:

<match:sub-dirs-only value="Sub-directories Only">
<match:sub-dirs-only value="Sub-directories Only">
<match:sub-dirs-only value="Sub-directories Only">
<revalidate>1046581729</revalidate>
</match:sub-dirs-only>
</match:sub-dirs-only>
</match:sub-dirs-only>

Notice that in no case was a directory component specified by name. In this sense,
“sub-dirs-only” matches can be interpreted as “*”.

this-dir This-dir matches restrict the application of metadata to the current path component
match rather than applying the metadata to all subdirectories.
The syntax for this path match is:
<match:this-dir value="This Directory Only">
</match:this-dir>

The following metadata example sets revalidation for the images directory but not for
any subdirectory of the images directory.
<match:recursive-dirs value="images">
<match:this-dir value="This Directory Only">
<revalidate>1046581729</revalidate>
</match:this-dir>
</match:recursive-dirs>

filename It is possible to match either a specific file or the default file within a directory. The
metadata tags are:
filename value="filename.ext": match an exact file within the current directory
filename value="No File Specified": match the default file within the current
directory

Match a Specific File To match a specific filename, the syntax is:

<match:filename value="file.ext" nocase="off" include-path-params="off">
</match:filename>

The value attribute takes a string that is the exact filename to match.
The nocase attribute is a Boolean to specify whether or not the match should be
case-sensitive. A setting of “on” makes the match case-insensitive. The default is “off.”

48 Akamai Content Control Interfaces. Akamai Confidential. NDA Required for Release.
 Match Tags

The include-path-params attribute is a Boolean to specify whether or not the

match should consider the path parameter as part of the string to match. The default
is “off.”
The following metadata example matches the index.html file in the root directory of
a domain only.
<match:this-dir value="This Directory Only">
<match:filename value="index.html">
<revalidate>1046581729</revalidate>
</match:filename>
</match:this-dir>

Matching the Default You can match the default file within a single directory using a special value for the
File filename match. The syntax is:
<match:filename value="No File Specified">
</match:filename>

“No File Specified” is a literal string used as the match value, because it is unlikely
anyone would have an existing file with this name. This value instructs the Akamai
server to apply metadata to whatever file the origin server would deliver as the default
if the directory were accessed without specifying a file. This is handy because not all
default files are .html.

Request Property Matches

These match tags evaluate some property of the request and apply metadata to the
request when the match evaluates to true. For example, you can apply metadata based
on whether or not the request headers include a particular cookie with a particular
value.

ext Matches the file extension in the request URL. This particular match type is not case
sensitive; that is, listing “gif ” as the extension to match will also match extensions
“GIF” “Gif ” “giF” etc.
The following example metadata revalidates all files with the extension .exe.
<match:ext value="exe">
<revalidate>1046581729</revalidate>
</match:ext>

The value argument accepts a space-separated list of strings that are the file extensions
to match. Again, this match is not case sensitive.
Note that this match is applied correctly in cases where the request URL includes a
query string. Given the example above, http://www.example.com/sample.exe?id=375
would match the extension “exe”. The extension is everything between the final dot
(.) in the last path segment and the end of the URL, the beginning of the query string
(if present), or beginning of parameters (if present). Parameters are separated from
the extension by a semicolon (;) and may contain variable=value settings.

cookie This match type matches on cookies received from the client (browser) in the Cookie
header. The syntax for this match type is:

Akamai Content Control Interfaces. Akamai Confidential. NDA Required for Release. 49
Enhanced CCU Request Format

<match:cookie name="user_id" op="present" value="">

Match tag properties for match:cookie are:

name: name of the cookie
The name attribute of this match type allows for wildcard characters (*) that will
match any character in a cookie name. In this feature, the wildcard will be “non-
greedy” and will match zero or more characters. This was introduced in 4.4. Exam-
ples:
*sessionid* matches: sessionid, xxsessionid, sessionidyy, xxsessionidyy, etc.
*sessionid matches: sessionid and xxsessionid but not sessionidyy or xxsession-
idyy.
sessionid* matches: sessionid and sessionidyy but not xxsessionid or xxsession-
idyy.
* matches all cookie names.
*a*a*a* matches a cookie name that has three letter 'a's anywhere in it.
If only one wildcard is used in a name and it's the last character, it would be equiva-
lent to setting the name-prefix-match property to on and not using the wildcard
character. In order to avoid any conflicts between name-prefix-match and the new
wildcard support, the Akamai edge server will ignore the special meaning of wildcards
in the cookie name when name-prefix-match is on and translate them literally as it
does now (again, this is for backward compatibility).
Given that browsers don't enforce any standards for cookie names, it's possible for
sites to use the wildcard character as part of the name, however that's very unlikely. In
order to support this corner case, users can “escape” the wildcard by using a backslash
in front of the wildcard to mean a literal wildcard. In turn, if the backslash is part of
the cookie name (again, very unlikely), users will have to escape the backslash by
another backslash. The purpose of the backslash is to force the edge server to translate
the character following it literally. Examples:
sessionid\* matches “sessionid*” exactly.
sessionid\*\\ matches “sessionid*\” exactly.
sessionid\** would match a cookie name that begins with “sessionid*”.
sessioni\d would match “sessionid” exactly. Notice that this example escaped
the letter 'd' which is not special. Akamai edge servers will allow for this in case a
customer accidentally escapes a non-special character.
name-prefix-match: sets whether the string in “name” must match the cookie name
exactly or be a prefix of the full cookie name. The property is a simple Boolean and
defaults to “off ”. This is particularly useful for matching “sessionid” cookies, where
the cookie name includes a unique string but has a constant prefix.
value: The full or partial value the cookie should have.
op: Match operation. Must be one of the following:

50 Akamai Content Control Interfaces. Akamai Confidential. NDA Required for Release.
 Match Tags

present: The given cookie name must be present in the HTTP headers.
missing: The given cookie name must not be present in the HTTP headers.
strcmp: The cookie must have exactly the given value.
strcasecmp: Same as strcmp but not case sensitive.
strstr: The cookie must have the given sub string (specified as the value).
strcasestr: same as strstr but not case sensitive.

Examples Match only if a cookie named “session_id” exists:

<match:cookie name="session_id" op="present" value="">

Match only if a cookie named “user_id” doesn't exist:

<match:cookie name="user_id" op="missing" value="">

Match only if a cookie named “logged_in” is set to “yes”:

<match:cookie name="logged_in" op="strcmp" value="yes">

Same thing matching “yes” case insensitively:

<match:cookie name="logged_in" op="strcasecmp" value="yes">

Match only if a cookie named “cust_type” has “_vip_” somewhere within it:
<match:cookie name="cust_type" op="strstr" value="_vip_">

Same thing matching “_vip_” case insensitively:

<match:cookie name="cust_type" op="strcasestr" value="_vip_">

Using Special If special characters are included in the value field, they must be embedded in exactly
Characters the way the origin server embeds them. For example, the space is considered a special
character in cookie values. If the origin server escapes it with %20, it must be escaped
with %20 in the value field. If the origin server doesn't escape it, it should not be
escaped. The problem is that browsers don't enforce escaping. How a value appears in
the request header really depends on how the origin server created it.
cpcode-range This match type matches on the content provider code (Billing Code). This match is
useful primarily in cases where a content provider has more than one CP code.
The current syntax is:
<match:cpcode-range value="50-55">
</match:cpcode-range>

When the match tag contains ranges, the starting and ending ranges are separated by
a dash '-' and different ranges are separated by a space. Here's an example:
<match:cpcode-range value="1-101 5381-5500 8000-8999">
</match:cpcode-range>

You can also specify a single number if there's no range:

<match:cpcode-range value="5381 5383 8000-8999 9001">
</match:cpcode-range>

Akamai Content Control Interfaces. Akamai Confidential. NDA Required for Release. 51
Enhanced CCU Request Format

You can specify a range to include all numbers after a particular number by listing an
open-ended range, like this:
<match:cpcode-range value="5000-">

arltype This match type matches on the format of the request ARL (Akamai Resource Loca-
tor). The syntax for this tag is:
<match:arltype value="v1-arl">

Possible values are “v1-arl”, “transparent”, “prepend”.

v1-arl – applies to any ARL that uses Typecodes. These are ARL’s used by the
FreeFlow service and generally look like this example:
http://a123.g.akamai.net/7/123/456/e358f5de00e9/www.example.com/logo.gif
prepend – applies to ARL's that use an ARL token but not a Typecode. The
ARL token is generally the same as the hostname in the Absolute URL portion of
an ARL. When it is an ARL token, this field can be any string; it doesn’t have to
conform to the format of a hostname.
transparent – is any ARL (actually a URL) that isn't one of the other two. It is
called “transparent” because it generally looks like a simple URL. This is the for-
mat generally used with Akamai edge server configurations.

Example:

The following metadata revalidate any requests that come in the form of a v1-ARL.
<match:arltype value="v1-arl">
<revalidate>1046581729</revalidate>
</match:arltype>

request-header This match type matches on the presence of a particular header or the contents of a
header in the client request. The syntax for this tag is:
<match:request-header operation="operation" argument1="string"
argument2="string">

A specific example would be:

<match:request-header operation="name-value-strcasestr"
argument1="Referer" argument2=".domain.com">

This the request-header tag includes an “operation” to specify what information to

look for in the header. The possible values for the operation tag are:
multiple-hosts
strstr
strcasestr
name-present
name-value-cmp
name-value-casecmp
name-value-strstr
name-value-strcasestr
regex

Each of these operations is described below with examples.

52 Akamai Content Control Interfaces. Akamai Confidential. NDA Required for Release.
 Match Tags

Negative Matching
Each of these match operations can be performed as a “negative match.” That is, the
match is successful if the conditions specified are not met. The syntax for the negative
match is formed by inserting an exclamation mark '!' before the operation name.
For example:
<match:request-header operation="!name-present" header-name="Referer">

This will cause the match to be evaluated to true if the given header name is not
present.
Special Case for Name-Value Matches
There's a special rule for the “name-value” functions for cases where the given header
name occurs multiple times in the request header. If the function is not being
negated, the match will evaluate to true if the given header value matches the value of
any of the headers. If the function is being negated, the match will only evaluate to
true if none of the values of the incoming header match the one specified in meta-
data.

multiple-hosts Matches requests whose header contains more than one Host header.
<match:request-header operation="multiple-hosts">

For operation="multiple-hosts", argument1 and argument2 are ignored and can be

left out or included without affecting edge server behavior.
!multiple-hosts matches if the request has no Host header or has just one Host
header.

strstr This match value requires an “argument1” property, which is a substring to match
anywhere in the entire request headers. The match is case-sensitive
<match:request-header operation="strstr" argument1="abc">

Argument2 is ignored and can be left out or included without affecting edge server
behavior.
!strstr: matches if the given substring is not in the header.

strcasestr Same as strstr except that it's not case sensitive.

<match:request-header operation="strcasestr" argument1="abc">

Argument2 is ignored and can be left out or included without affecting edge server
behavior.
!strcasestr matches if the given substring is not in the header. The match is not case
sensitive.

name-present This operation matches requests that contain the given request header. This match is
not case sensitive. Argument1 specifies the header name.
<match:request-header operation="name-present" argument1="Referer">

Akamai Content Control Interfaces. Akamai Confidential. NDA Required for Release. 53
Enhanced CCU Request Format

Argument2 is ignored and can be left out or included without affecting edge server
behavior.
!name-present matches if the given header name is not part of the request headers.

name-value-cmp Matches requests where a request header with a specified name (argument1) matches
the given header-value (argument2). The match must be exact, rather than a sub-
string of the header value. The match is case sensitive.
<match:request-header operation="name-value-cmp" argument1="User-Agent"
argument2="Custom Agent">

!name-value-cmp matches if either the given header name is not present or its value
doesn't match the one specified in metadata.

name-value-casecmp This match functions like name-value-cmp except that the match is not case sensi-
tive.
<match:request-header operation="name-value-casecmp" argument1="user-
agent" argument2="custom-agent">

!name-value-casecmp: matches if either the given header name is not present or its
value doesn't match the one specified in metadata. The match is not case sensitive.

name-value-strstr This operation matches requests where the specified header (argument1) contains the
given sub-string (argument2)somewhere in its value. The match is case sensitive.
<match:request-header operation="name-value-strstr" argument1="Referer"
argument2=".domain.com">

!name-value-strstr: matches if either the given header name is not present or the sub-
string specified in metadata is not part of the header's value.

name-value-strcasestr Same as name-value-strstr above except that the match is not case sensitive.
<match:request-header operation="name-value-strcasestr"
argument1="Referer" argument2=".domain.com">

!name-value-strcasestr: matches if either the given header name is not present or the
sub-string specified in metadata is not part of the header's value. The match is not
case-sensitive.

regex Matches on a regular expression pattern using extended regular expressions

For example:
<match:request-header operation="regex" argument1="ab[cd]">

request-type This matches on the type of request the Akamai server receives. Possible values for the
tag are: 'user,' 'esi-fragment,' 'esi-war,' and 'esi-tunnel.'
<match:request-type value="esi-fragment">
</match:request-type>
esi-fragment matches on fragment requests going from ESI->edge server->origin
and back from origin->edge server->ESI.
esi-war matches on WAR requests going from ESI->edge server->origin and back
from origin->edge server->ESI.
54 Akamai Content Control Interfaces. Akamai Confidential. NDA Required for Release.
 Match Tags

esi-tunnel matches on request-mod (EdgeJava) requests going from ESI->edge

server->ej-tomcat and back from ej-tomcat->edge server->user. It's used to for-
ward requests to the local Java app server. This is the only request-type that's not
applicable to cacheh since all request-mod requests go to the local Java app server.
user matches everything else. This maintains backward compatibility with the
esi-fragment match type, which matched on whether a request was for a frag-
ment, or not for a fragment. User registers a positive match if the request is not
any of the other types (esi-fragment, esi-war, esi-tunnel).
The edge server allows multiple values for the request-type match with a comma sep-
arator to indicate that the match should evaluate to true if any of the request types
match, for example:
<match:request-type value="user,esi-tunnel,esi-war">

The old match type <match:esi-fragment value="on|off"> was adjusted for backward
compatibility so that the 'on' setting is the same as <match:request-type value="esi-
fragment"> and the 'off' setting is the same as <match:request-type value="user">

method This match type allows for application of metadata based on the method used in the
request (GET, POST, HEAD and any others recognized by Akamai edge servers).
The match is case insensitive.
<match:method value="pOsT">
<revalidate>1046581729</revalidate>
</match:method>

protocol This tag matches on the protocol used in the incoming request.
<match:protocol value="HTTPS">
<revalidate>1046581729</revalidate>
</match:protocol>

Acceptable values are “HTTPS” or “HTTP”. When the client connects through SSL
HTTPS produces a match, otherwise HTTP is a match.

query-string This tag matches on an argument in the query string with functionality similar to
what is available for matching on cookies. The tag can match for whether the query
string argument:
• is either present or missing
• has or doesn't have a particular value
• has or doesn't have a particular sub string inside it
The matching functions can be specified as either case sensitive or case insensitive.
The metadata tag is:
<match:query-string name=”arg-name” name-prefix-match=”off”
op=”operation-type”>

The properties are as follows:

name: Contains the name of the argument in the query string to match against.
(the edge server looks for this name in the query string using a case sensitive
match).

Akamai Content Control Interfaces. Akamai Confidential. NDA Required for Release. 55
Enhanced CCU Request Format

name-prefix-match: This is a flag that indicates whether the parameter name

given (above) is just a prefix. The default is off.
op: Indicates the match operation to perform. It has to be one of the following
five values. Each of these can be testing for the negative by preceding the op
name with an exclamation point (for example, “!name-present”)
name-present: to check whether given parameter name is present
strcmp: The given parameter contains the given value.
strcasecmp: Same as strcmp but not case sensitive.
strstr: The given parameter contains the given sub string.
strcasestr: same as strstr but not case sensitive.
wildcard: case sensitive match where “*” represents zero or more characters
and “?” represents one character.
wildcardcase: same as wildcard but not case sensitive
value: Contains the value/sub-string to match against. (Note: if you want to
match against the absence of a value, the edge server will accept value="" and
perform the match correctly. However, in version 4.3, MUI will not permit this
syntax, so you need to enter it by hand. This limitation will be addressed in ver-
sion 4.4)
unescape: Indicates how to unescape the query parameter's value before the
match operation:
none: the query string value will be compared as is (this is the default)
url-unescape: the query string value will be url unescaped before the
comparison

Examples

Check whether the “sessionid” query string parameter is present:

<match:query-string op="name-present" name="sessionid">

Check whether the “sessionid” query string parameter is missing:

<match:query-string op="!name-present" name="sessionid">

Check whether the “account” query string parameter contains the value “valid” (case
insensitively):
<match:query-string op="strcasecmp" name="account" value="valid">

Check whether the “account” query string parameter contains a value other than
“valid” (case sensitively):
<match:query-string op="!strcmp" name="account" value="valid">

Check whether the “product_name” query string parameter contains the word “com-
puter” anywhere inside it (case sensitively):
<match:query-string op="strstr" name="product_name" value="computer">

56 Akamai Content Control Interfaces. Akamai Confidential. NDA Required for Release.
 Match Tags

Check whether the “product_name” query string parameter doesn't contain the word
“computer” (case sensitively):
<match:query-string op="!strstr" name="product_name" value="computer">

typecode This match tag makes it possible to apply metadata to v1 ARL requests with a partic-
ular typecode. The value of the tag is a space-separated list of typecode characters.
<match:typecode value="5 7">
...
</match:typecode>

Response Property Matches

response-header This match tag matches on characteristics of the response header. In specific, this tag
was implemented to facilitate matching on MIME type and HTTP Reply Status
code.
The syntax for the tag is:
<match:response-header operation="enum" argument1="headername or status-
code" argument2="string">
</match:response-header>

The functionality of this match type is very similar to the request-header match type.
Like the request-header match, the response header match has three properties:
operation: Describes the type of matching to perform. All operations, except the
numeric comparisons, can be negated by prefixing them with an exclamation
point “!”. Possible values are:
status: Match on the response status code
name-present: Checks whether the given header name is present in the
request.
name-value-cmp: Checks whether the contents of the given header matches
the given value case sensitively.
name-value-casecmp: Same as name-value-cmp except it's case insensitive
name-value-strstr: Checks whether the contents of the given header
contains the given substring case sensitively.
name-value-strcasestr: Same as name-value-strstr except it's case insensitive
name-value-num-eq: (numeric comparison: ==) Checks whether the
contents of the given header is numeric and whether it is equal to the given
value.
name-value-num-ne: (numeric comparison: !=)
name-value-num-lt: (numeric comparison: <)
name-value-num-le: (numeric comparison: <=)
name-value-num-gt: (numeric comparison: >)
name-value-num-ge: (numeric comparison: >=)

Akamai Content Control Interfaces. Akamai Confidential. NDA Required for Release. 57
Enhanced CCU Request Format

argument1: contains the header-name to match against for all operations except
'status'. For 'status', it has to be a status code (or list/range of codes) to match
against. The range can be specified in the same syntax used by the cpcode-range
match tag.
argument2: contains the value to match against for all operations except 'status'.
For the numeric operators, only integer values are considered. If the header's
value is not numeric, the comparison won't be executed. The value supplied by
the user (in argument2) is on the right and the value from the response header is
on the left of the operator:
header-value (==,!=,<,<=,>,>=) user-supplied-value
The largest number that the edge server can handle in this comparison is (231 - 1)
or (2147483647).

Examples:

The following example would require revalidation of any object that contained the
HTTP header “Custom-Identifier” with a value of “a2f9e724”. A scheme of this
nature might be useful for forcing revalidation of all files that are related. This rela-
tionship would be expressed by the value of the Custom-Identifier.
<match:response-header operation="name-value-cmp"
argument1="Custom-Identifier" argument2="a2f9e724">
<revalidate>1046581729</revalidate>
</match:response-header>

58 Akamai Content Control Interfaces. Akamai Confidential. NDA Required for Release.