How-To Rewrite URLs for Object Storage Sites Using EdgeRules

Serving static sites from 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.

Using the API

There are four required pieces of information in order to add EdgeRules via the API:

1. Bearer Token
2. Stack ID/slug
3. Site ID
4. Scope ID

This guide walks through how to get a bearer token. The site and stack IDs can be found in the address bar of the site overview in the control panel: https://control.stackpath.com/stacks/{stack_slug}/sites/{site_id}/overview. An API call is required to retrieve the Scope ID.

Remember to send the bearer token with every request (besides the original request to the authentication endpoint).

Get Scope IDs

REQUEST

METHOD: GET

Endpoint: https://gateway.stackpath.com/cdn/v1/stacks/{stack_slug}/sites/{site_id}/scopes


Response:

{
   "pageInfo": {
     "totalCount": "3",
     "hasPreviousPage": false,
     "hasNextPage": false,
     "endCursor": "2"
  },
  "results": [
    {
      "id": "f26a8dce-62f2-11ea-bc55-0242ac130003",
      "platform": "CDS",
      "path": "/"
    },
    {
      "id": "ffaf45d8-62f2-11ea-bc55-0242ac130003",
      "platform": "CDS",
      "path": "/wcs_061255c8-62f3-11ea-bc55-0242ac130003"
    },
    {
      "id": "0ad15b7c-62f3-11ea-bc55-0242ac130003",
      "platform": "ALL",
      "path": "/"
    }
  ]
}

From this list of results, the desired ID is for the CDS platform and the / path (f26a8dce-62f2-11ea-bc55-0242ac130003 in this example).

In the following examples, CAPITAL LETTERS will be used to indicate portions of the request which should be replaced with site-specific information.

Rewrite Root Document to /index.html

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

Rewrite

Browser URL: https://DOMAIN.COM/

Modified Request: https://DOMAIN.COM/index.html

Create EdgeRule

REQUEST

METHOD: POST

Endpoint: https://gateway.stackpath.com/cdn/v1/stacks/{stack_id}/sites/{site_id}/scopes/{scope_id}/rules

Request Body:

{
  "name": "RULENAME",
  "slug": "RULE-NAME",
  "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:

Rewrite

Browser URL: https://DOMAIN.COM/folder/path/

Modified Request: https://DOMAIN.COM/folder/path/index.html

Create EdgeRule

REQUEST

METHOD: POST

Endpoint: https://gateway.stackpath.com/cdn/v1/stacks/{stack_id}/sites/{site_id}/scopes/{scope_id}/rules

Request Body:

{
  "name": "RULENAME",
  "slug": "RULE-NAME",
  "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.

Rewrite

Browser URL: https://EXAMPLE.DOMAIN.COM/folder/path/

Modified Request: https://DOMAIN.COM/EXAMPLE.DOMAIN.COM/folder/path/index.html

Browser URL: https://EXAMPLE.DOMAIN.COM/folder/path/file

Modified Request: https://DOMAIN.COM/EXAMPLE.DOMAIN.COM/folder/path/file.html

Update EdgeRule

REQUEST

METHOD: PATCH

Endpoint: https://gateway.stackpath.com/cdn/v1/stacks/{stack_id}/sites/{site_id}/scopes/{scope_id}/rules/{rule_id}/configuration

Request Body:

{
  "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.

If any questions arise or any assistance can be further provided, feel free to drop us a line at hi@stackpath.com or open up a chat with our 24/7 live support, we'll be happy to help you out.