Guides

Rewriting URLs for Object Storage Sites Using EdgeRules

Serving static sites from StackPath's object storage has many benefits, but adjusting URLs can be a challenge without a server to handle the logic. With EdgeRules, it is possible to rewrite requests on-the-fly, without using redirects.

For example, when a user visits a static site at domain.com, it may be intended to serve the file domain.com/index.html, without redirecting or showing the whole filename and filetype in the URL.

This guide will walk through how to set up some basic rules via the API for serving full static sites from an object storage bucket.

Rewrite Root Document to /index.html

With a clientRequestModification EdgeRule, it is possible to rewrite client requests at the CDN without requiring a redirect.

For the example below, we will take the URL https://domain.com and modify the request at the CDN level, rewriting it to https://domain.com/index.html.

This requires an EdgeRule, which we will create by making a call to the Create an EdgeRule endpoint:

curl --request POST \
  --url https://gateway.stackpath.com/cdn/v1/stacks/STACK_ID/sites/SITE_ID/scopes/SCOPE_ID/rules \
  --header 'accept: application/json' \
  --header 'authorization: Bearer BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '
{
  "name": "test rule",
  "configuration": {
    "clientRequestModification": [
      {
        "urlPattern": "regex:(^https://domain.com/$)",
        "urlRewrite": "%client.request.protocol%://%client.request.host%index.html",
        "flowControl": "break",
        "enabled": true,
        "methodFilter": "GET",
        "clientRequestFilter": []
      }
    ]
  }
}

Rewrite All URLs with trailing slashes to /path/index.html

As an example of a slightly more complicated rewrite, all URLs can be rewritten with a trailing / , using the same path but adding index.html at the end.

For the example below, we will take the URL https://domain.com/folder/path/ and modify the request at the CDN level, rewriting it to https://domain.com/folder/path/index.html.

The API call used to create this EdgeRule would appear as follows:

curl --request POST \
  --url https://gateway.stackpath.com/cdn/v1/stacks/STACK_ID/sites/SITE_ID/scopes/SCOPE_ID/rules \
  --header 'accept: application/json' \
  --header 'authorization: Bearer BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '
{
  "name": "test rule",
  "configuration": {
    "clientRequestModification": [
      {
        "urlPattern": "regex:(^https://domain.com.*/$)",
        "urlRewrite": "%client.request.protocol%://%client.request.host%%client.request.fullFilePath%index.html",
        "flowControl": "break",
        "enabled": true,
        "methodFilter": "GET",
        "clientRequestFilter": []
      }
    ]
  }
}

Updating an Existing EdgeRule

During setup, it can be helpful to edit existing EdgeRules rather than deleting and re-creating them. To do this, the rule_id value is required, which is returned when you first create the rule.

When updating a rule, each category of configuration that is defined (e.g. clientRequestModification) will be entirely rewritten. To keep existing parts of that category, they must be included in the body with the update.

For the example below, we are taking two URLs, https://example.domain.com/folder/path/ and https://example.domain.com/folder/path/file, and modifying these requests at the CDN level, rewriting them to https://domain.com/example.domain.com/folder/path/index.html and https://domain.com/example.domain.com/folder/path/file.html respectively.

We can do this by sending a PATCH request to the Update an EdgeRule's configuration endpoint:

curl --request POST \
  --url https://gateway.stackpath.com/cdn/v1/stacks/STACK_ID/sites/SITE_ID/scopes/SCOPE_ID/rules \
  --header 'accept: application/json' \
  --header 'authorization: Bearer BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '
{
  "configuration": {
    "clientRequestModification": [
      {
        "urlPattern": "regex:(^https://.*.domain.com/.*$)",
        "urlRewrite": "%client.request.protocol%://domain.com/%client.request.host%%client.request.fullFilePath%%client.request.params%",
        "flowControl": "next",
        "enabled": true,
        "methodFilter": "GET"
      },
      {
        "urlPattern": "regex:(^https://domain.com.*/[^.\/]+$)",
        "urlRewrite": "%client.request.protocol%://%client.request.host%%client.request.fullFilePath%.html",
        "flowControl": "break",
        "enabled": true,
        "methodFilter": "GET",
        "clientRequestFilter": []
      },
      {
        "urlPattern": "regex:(^https://domain.com.*/$)",
        "urlRewrite": "%client.request.protocol%://%client.request.host%%client.request.fullFilePath%index.html",
        "flowControl": "next",
        "enabled": true,
        "methodFilter": "GET",
        "clientRequestFilter": []
      }
    ]
  }
}

The above rule will provide the ability to simulate subdomains under the same bucket by serving those subdomains from subfolders, as well as adding .html to filenames and index.html to paths.

Updated 30 days ago