Skip to main content

Redirect Handler

Learn how to redirect users from one URL to another using HTTP redirects, perfect for site migrations, URL restructuring, or directing users to updated content.

Drago Crnjac avatar
Written by Drago Crnjac
Updated over a month ago

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

location

string

Yes

The URL to redirect to (must be a valid URL starting with http:// or https://)

status_code

integer

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

{http.request.uri}

The full request URI

For https://site.com/blog/post?id=123, this would be https://site.com/blog/post?id=123

{http.request.uri.path}

The path component only

For /blog/post?id=123, this would be /blog/post

{http.request.uri.path.dir}

The directory part of the path

For /blog/post/123.html, this would be /blog/post

{http.request.uri.path.file}

The filename part of the path

For /blog/post/123.html, this would be 123.html

{http.request.uri.query}

The query string without ?

For /blog/post?id=123&author=jane, this would be id=123&author=jane

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!

Did this answer your question?