What is the Rewrite Handler?

The Rewrite Handler allows you to transform the URL of incoming requests before they reach your upstream server. This lets you modify paths, add or remove query parameters, or completely change the destination of a request without requiring client-side redirects. The rewriting happens transparently to the user, as their browser address bar still shows the original URL.

How Rewrite Handler Works

When a rule with a Rewrite Handler matches an incoming request, the handler transforms the request URL based on your specified pattern before forwarding the request to your upstream server. This is powerful for changing how URLs are structured internally without affecting external-facing URLs.

Unlike redirects (which send the user to a new URL), rewrites happen behind the scenes. The user's browser continues to show the original URL, while the content comes from the rewritten URL on your server.

Configuration Options

The Rewrite Handler supports this configuration option:

Option	Type	Required	Description
`uri`	`string`	Yes	The pattern that defines how the URL should be rewritten, can include placeholders

Rewrite URI Placeholders

You can use these placeholders in your rewrite 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`

API Reference

When working with Rules through the API, Rewrite handlers are represented in JSON format. This is the same structure used in the API endpoints for creating and updating rules.

{
  "type": "rewrite",
  "uri": "https://blog.example.com{http.request.uri.path}?source=proxy&{http.request.uri.query}"
}

In API requests, this handler would be included in the handlers array of a rule object:

{
  "name": "Blog Rewrite Rule",
  "active": true,
  "matchers": [
    {
      "type": "path",
      "value": "/blog",
      "operator": "starts_with"
    }
  ],
  "handlers": [
    {
      "type": "rewrite",
      "uri": "https://blog.example.com{http.request.uri.path}?source=proxy&{http.request.uri.query}"
    }
  ]
}

Configuration Examples

Example 1: Basic Path Rewriting

This matcher and handler combination will rewrite requests from /articles/* to /blog/* while preserving the query parameters:

In the UI:

In the API (only Rewrite Handler):

{
  "type": "rewrite",
  "uri": "https://example.com/blog{http.request.uri.path}"
}

For example, a request to /articles/2023-year-review.html would be rewritten to https://example.com/blog/articles/2023-year-review.html.

Example 2: Content Versioning

This handler adds a version prefix to backend requests:

In the UI:

In the API:

{
  "type": "rewrite",
  "uri": "https://content.example.com/v2{http.request.uri.path}?{http.request.uri.query}"
}

Users accessing your site with the original URLs will be served content from the v2 paths on your server.

Common Use Cases

Here are some popular ways to use the Rewrite Handler:

Website Restructuring

Maintain old URLs while updating your site's architecture:

Create a rule with a Path matcher for old URL patterns
Add a Rewrite handler to transform requests to new URL structures
Users can continue using old bookmarks while you serve content from the new structure

Migrating Content

Seamlessly move content between different areas of your site:

Match requests to old content locations
Rewrite them to new content locations
No need for client-side redirects that change the URL in the browser

Backend Service Integration

Connect multiple backend services under a single domain:

Create path-based rules for different sections of your site
Use rewrites to direct traffic to the appropriate backend service
Present a unified experience to users while using specialized services behind the scenes

Internationalization

Serve localized content based on path patterns:

Match requests with locale identifiers (e.g., /en-us/products)
Rewrite them to your internal content structure (e.g., /products?locale=en-us)
Maintain clean, user-friendly URLs while keeping your backend simple

API Versioning

Support multiple API versions with a clean URL structure:

Create rules matching your API endpoints
Use rewrites to direct traffic to the appropriate API version on your backend
Simplify client code by providing consistent URLs across API versions

AB Testing

Split traffic between different backend implementations:

Create rules that match the pages you want to test
Use a randomization technique in your backend routing
Rewrite requests to different implementations based on your testing criteria

Combining with Other Handlers

The Rewrite handler works well when combined with:

Set Response Header: Add custom headers based on the rewritten URL
Replace Response: Modify the response content to match the original URLs
Delete Response Header: Remove any headers that might expose the internal URL structure

Remember that the Rewrite handler should typically be placed before handlers that modify the response, as it changes the destination of the request before it reaches your server.

Best Practices

Keep rewrites as simple as possible for better performance
Use the most specific placeholder that meets your needs
Include the query string placeholder when appropriate to preserve user parameters
Test your rewrites thoroughly with different URL scenarios
Use consistent patterns across similar rules
Document your rewrite rules for future maintenance
Consider SEO implications of rewriting vs. redirecting

Troubleshooting

If your Rewrite handler isn't working as expected:

Check that your matchers are correctly identifying the requests
Verify that your placeholder syntax is correctly formatted
Test with simpler rewrites first, then add complexity
Check your server logs to see the actual rewritten URLs that reached your upstream / origin server
Consider any path normalization that might be happening
Ensure your upstream server can handle the rewritten paths
Be careful of infinite rewrite loops if combining multiple rules

Limitations

Rewrites affect only the request URL, not other aspects of the request
If you need to change the visible URL in the browser, use redirects instead
Complex parsing of URL components beyond the provided placeholders requires more advanced handling

The Rewrite handler provides powerful control over your URL structure without requiring client-side redirects. By strategically using rewrites, you can maintain a clean, consistent URL structure for users while implementing whatever backend architecture best serves your needs.

Until next time, keep building!

Need more help? Reach out via the Intercom chat widget and we'll be right with you!