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:
- Bearer Token
- Stack ID/slug
- Site ID
- 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
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
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
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
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.