This behavior automates common URL rewriting tasks for incoming requests before they are forwarded to the origin.

Why you need it

Use this behavior to:

Offload the origin server from URL rewriting tasks and perform them at the edge to increase performance.
Direct certain requests to certain objects towards new sections of the origin without changing the references in the html pages.
Hide the origin directory structure from the public.

How it works

By default, the outgoing path and incoming path are the same, but you can make changes by replacing parts of the path, setting the entire path to a static value, or adding values to the beginning of the path.

The behavior is controlled by the first option, Action, which defines what the Akamai edge server does with the incoming requests.

Features and options

Remove part of the incoming path

This identifies a path component in the incoming URL and removes it before forwarding it to the origin. When this operation is selected, use the Find in Incoming Path field to specify which component needs to be removed. A path component is similar to a directory structure and must begin and end with a /. The format of the path component is enforced by Property Manager.

You can optionally use the Keep the Query Parameters option to define how query strings are handled with these requests. This defaults to Yes to preserve incoming query strings.

Example

Incoming URL: http//www.example.com/path1/path2/page.html?param=2
Find in Incoming Path: This is set to /path2/.
Keep the Query Parameters: This is set to Yes.
Resulting forwarded URL after rewrite: http//www.example.com/path1/page.html?param=2

The edge server looks for all occurrences of path2 in this case and removes them. For example, if the incoming URL was http//www.example.com/path1/path2/path3/path2/page.html, then the forwarded URL is http//www.example.com/path1/path3/page.html.

Replace part of the incoming path

This identifies a path component in the incoming URL and replaces it with another path component before forwarding it to the origin. When selected, use the Find in Incoming Path field to specify which component needs to be replaced. Then, specify the replacement in Replace With. Ensure that both fields include valid path components.

You can optionally use Keep the Query Parameters to define how query strings are handled with these requests. This defaults to Yes to preserve any incoming query strings.

Example

Incoming URL: http//www.example.com/path1/tobereplaced/page.html?param=1
Find in Incoming Path: This is set to /tobereplaced/.
Replace With: This is set to /replacement/.
Keep the Query Parameters: This is set to No.
Resulting forwarded URL after rewrite: http//www.example.com/path1/replacement/page.html

The edge server looks for all occurrences of /tobereplaced/ in this case, and replaces them. For example, if the incoming URL was http//www.example.com/path1/tobereplaced/path3/tobereplaced/page.html, then the forwarded URL is http//www.example.com/path1/replacement/path3/replacement/page.html

Prepend the incoming path

This adds a path component prefix to the beginning of the incoming URL. When selected, use Prepend with to specify the prefix.

You can optionally use Keep the Query Parameters to define how to handle query strings are handled with these requests. This defaults to Yes to preserve any incoming query strings.

Example

Incoming URL: http//www.example.com/path1/page.html?param=1
Prepend With: This is set to /prefix/.
Keep the Query Parameters: This is set to Yes.
Resulting forwarded URL after rewrite: http//www.example.com/prefix/path1/page.html?param=1

Replace the entire path

Use this to replace the entire path after the initial URL with a path you define. When this operation is selected, use Replace with to specify the new path. Requests are forwarded to this new path.

Example

Incoming URL: http://www.example.com/path1/page.html
Replace with: This is set to /new/url/index.html?param=1.
Resulting forwarded URL after rewrite: http://www.example.com/new/url/index.html?param=1

Regular expression replacement

Perl compatible regular expression: Use this to specify match patterns you want to replace in the outgoing path. For example: ^(?i:\\Q/htdl\\E)
Replacement: Use this to specify the replacement operation that corresponds to the regular expression. You can use references to parts of the regular expression to perform the replacement. Replacement variables use capture groups $1 through $9. You don't need to escape the $ symbol in the replacement field.

📘
With the Regular Expression Replacement option, format validation is not applied to the input fields. Akamai recommends that you thoroughly test these settings in the staging environment before your go live in production. Contact your Akamai technical representative with any questions.

Regex replacement example

Imagine a scenario where your image files are spread out internally on your origin server across multiple directories. The external path to access some of your images uses this format:

/{directory-1}/images/{image-name}

where

{directory-1} is a directory where the first character is a lower-case a followed by one or more letters or digits,
{image-name} is the name of the image file. It consists of letters and digits with either a 3-character or 4-character file extension that can consist of letters or digits.

You want to change your backend image folder structure and move the images which match the above format to a new folder structure. You want to skip some other images, so you need to modify the forward path only for certain image requests.

Valid requests

These examples would all be valid request URLs for images sent from the client, which should be modified when going forward:

/a123/images/cool-image.png
/aA1B2c3/images/another-image.JPEG
/ab/images/myimage.a1b

Invalid requests

You don't want to modify the outgoing request path if:

the first character is not an a. Therefore, this sample incoming path shouldn't be modified going forward /b123/images/cool-image.png
the subsequent characters in {directory-1}are not all upper-case or lower-case letters or digits. Therefore, this sample incoming path shouldn't be modified going forward /a-1B2/images/another-image.JPEG
the file extension is invalid or the file extension doesn't exist. Therefore, this sample incoming path shouldn't be modified going forward /a123/images/image-name.jp

Solution

As you are restructuring the image folder structure on your origin server, you want to translate valid incoming paths to a forward path in this format:

/newimages/{directory-2}/{image-name}

where {directory-2} is the same as the incoming {directory-1} but with the leading a replaced by dir-.

To achieve this:

In the Perl Compatible Regular Expression field, type \/a([a-zA-Z0-9]+)\/images\/(.\*?\.(?:[a-zA-Z0-9]){3,4})
In the Replacement field, type /newimages/dir-$1/$2

The valid incoming requests would then convert to the respective forward paths:

/a123/images/cool-image.png>/newimages/dir-123/cool-image.png
/aA1B2c3/images/another-image.JPEG>/newimages/dir-A1B2c3/another-image.JPEG
/ab/images/myimage.a1b>/newimages/dir-b/myimage.a1b

You can determine how often these replacements happen

This is controlled by using the Occurrences setting. You can choose to replace or remove the old value the first time it appears, or every time it appears.

Other important considerations

All examples here assume that the incoming host header is being forwarded to the origin.
All rewrite operations change the cache-key, which may or may not affect the performance and offload of your property.
You can't override the Origin Base Path with any rewrite operations within this behavior.