What is the Redirect Handler?
The Redirect Handler allows you to send users from one URL to another by issuing HTTP redirect responses. Unlike the Rewrite Handler (which changes URLs behind the scenes), redirects actually change the URL in the user's browser. This makes redirects visible to users and search engines, ensuring they update their bookmarks and indexes to the new location.
How Redirect Handler Works
When a rule with a Redirect Handler matches an incoming request, the handler immediately returns a redirect response with the specified status code and location URL. The user's browser then automatically requests the new location. This happens before any request reaches your upstream server, saving server resources.
Redirects are commonly used in two forms:
301 Permanent Redirects: Tell clients and search engines that a URL has moved permanently
302 Temporary Redirects: Indicate that a URL is temporarily available at a different location
Configuration Options
The Redirect Handler requires these configuration options:
Option | Type | Required | Description |
|
| Yes | The URL to redirect to (must be a valid URL starting with http:// or https://) |
|
| Yes | The HTTP status code to use for the redirect (must be either 301 or 302) |
Redirect Placeholders
You can use these placeholders in your URI to preserve parts of the original URL:
Placeholder | Description | Example |
| The full request URI | For |
| The path component only | For |
| The directory part of the path | For |
| The filename part of the path | For |
| The query string without | For |
Simple Placeholder Examples
Example 1: Keeping the path but changing the domain
{
"type": "redirect",
"location": "https://new-domain.com{http.request.uri.path}?{http.request.uri.query}",
"status_code": 301
}
A request to https://old-domain.com/products/item42?utm_source=abc
would redirect to https://new-domain.com/products/item42?utm_source=abc
.
Example 2: Preserving query parameters
{
"type": "redirect",
"location": "https://example.com/new-page?{http.request.uri.query}",
"status_code": 302
}
A request to /old-page?id=123&category=shoes
would redirect to https://example.com/new-page?id=123&category=shoes
.
Example 3: Moving files to a new directory structure
{
"type": "redirect",
"location": "https://example.com/documents/archive/{http.request.uri.path.file}",
"status_code": 301
}
A request to /files/report.pdf
would redirect to https://example.com/documents/archive/report.pdf
.
API Reference
When working with Rules through the API, Redirect handlers are represented in JSON format. This is the same structure used in the API endpoints for creating and updating rules.
{
"type": "redirect",
"location": "https://new-location.example.com/destination",
"status_code": 301
}
In API requests, this handler would be included in the handlers array of a rule object:
{
"name": "Permanent Redirect Rule",
"active": true,
"matchers": [
{
"type": "path",
"value": "/old-page",
"operator": "is"
}
],
"handlers": [
{
"type": "redirect",
"location": "https://example.com/new-page",
"status_code": 301
}
]
}
Read full Rules API documentation here.
Configuration Examples
Example 1: Simple Permanent Redirect
This handler will permanently redirect users from an old URL to a new one:
In the UI:
In the API:
{
"type": "redirect",
"location": "https://domain.com/blog",
"status_code": 301
}
Example 2: Temporary Redirect for Maintenance
This handler will temporarily redirect users during maintenance:
In the UI:
In the API:
{
"type": "redirect",
"location": "https://example.com/maintenance-page",
"status_code": 302
}
Example 3: Domain Change Redirect
This handler will redirect users to a new domain:
In the UI:
In the API:
{
"type": "redirect",
"location": "https://new-brand.com{http.request.uri.path}?{http.request.uri.query}",
"status_code": 301
}
Common Use Cases
Here are some popular ways to use the Redirect Handler:
Site Migrations
Smoothly transition users when moving content:
Create rules matching old URLs with Path matchers
Use Redirect handlers with 301 status codes to point to new locations
Preserve SEO value and user bookmarks during migration
URL Structure Changes
Update your URL scheme without losing visitors:
Map old URL patterns to new ones
Use permanent redirects for structural changes
Ensure search engines update their indexes
Temporary Content Relocations
Direct users to alternative content temporarily:
Use 302 redirects for content that's temporarily moved
Create specific path matches for affected areas
Restore normal operation by disabling the rule when done
Domain Consolidation
Bring multiple domains under a single brand:
Create rules for requests to legacy domains
Redirect users to corresponding pages on the primary domain
Use 301 status codes to indicate permanent moves
Protocol Enforcement
Ensure all traffic uses secure connections:
Match HTTP requests using Method and Path matchers
Redirect to HTTPS versions of the same URL
Use 301 redirects to indicate HTTPS is the canonical version
Geographic or Language Redirects
Direct users to region-specific content:
Create rules based on Headers (Accept-Language, IP-based)
Redirect to appropriate localized versions
Consider using 302 redirects to allow users to change preferences
Compared to Other Solutions
Redirect vs. Rewrite
Redirects: Change the URL in the browser; visible to users; create a new request
Rewrites: Change URLs behind the scenes; not visible to users; same request continues
Redirect vs. Static Response + Set Response Header
Redirect Handler: Simple, purpose-built solution for standard redirects
Static Response + Headers: More flexible for complex scenarios requiring custom headers or more complex logic
Best Practices
Use 301 (permanent) redirects for content that has permanently moved
Use 302 (temporary) redirects for temporary changes or testing
Keep redirect chains minimal (avoid redirects that point to other redirects)
Ensure destination URLs are valid and accessible
Test redirects thoroughly before deploying to production
Document your redirects for future reference
Consider the SEO impact of your redirect strategy
Use specific path matching rather than catch-all redirects when possible
Monitor redirects for unexpected behavior or loops
Troubleshooting
If your Redirect handler isn't working as expected:
Verify that your matchers are correctly identifying the requests
Ensure your destination URL is a valid, complete URL (starting with http:// or https://)
Check that you're using the correct status code (301 or 302)
Use browser developer tools to inspect the actual redirect
Check for redirect loops or chains that might cause issues
The Redirect handler provides a straightforward way to implement HTTP redirects for your domain. By strategically using redirects, you can ensure users and search engines can find your content even as your site structure evolves.
Until next time, keep building!
Need more help? Reach out via the Intercom chat widget and we'll be right with you!