An HTTP rewrite (also called a URL rewrite) is an HTTP protocol feature that uses expressions to redirect or block incoming web requests. This often involves the web server or an intermediary proxy configured with a pattern — such as rewriting any path starting with /images/ to /static/images/ instead. They'll then either issue the client a 3XX response code, telling it to ask for the new URL instead, or silently serve the new path to the client.

HTTP rewrites ensure that clients are connected to the resources they've requested. URLs reachable via web servers can change regularly as resources are changed, added, or removed. Web resources are like living things in that they can change internally anytime, for any reason. HTTP rewrites can help reduce the negative impacts of such backend changes while delivering a smoother browsing experience for users. They allow servers to function more intelligently by transforming problematic URLs into valid addresses. 

HTTP rewrites came into being as the HTTP protocol evolved, with support becoming stronger in HTTP/1.1. It's also worth noting that HTTP rewrites rely on web server technologies to function properly instead of being a standalone feature. They became much more popular with the rise of Apache and alternative server softwares.

How does an HTTP rewrite work?

HTTP rewrites are often mentioned alongside HTTP redirects, even though both mechanisms are unique. Rewrites occur on the server side and give no indication that a rewrite even happened. They're invisible and minimally disruptive. Meanwhile, a redirect (or URL redirect) happens on the client side and is noticeable as new content starts loading. 

We have two types of HTTP rewrites: 

  • Static – Replaces a portion of the request URL, which can be a query OR string, with a new static string

  • Dynamic – Allows you to define paths or query strings using a rewrite expression

Today, the widespread popularity of CMSes for content publishing and updating have made dynamic rewrites more popular. The resources behind these platforms are changing often and may be too complex to manage using static HTTP rewrites.

HTTP rewrite status codes and directives

There are a variety of actions that can be performed on a URL to rewrite, redirect, or reject it in HAProxy:

  • http-request redirect location – Returns a 3XX status code to the client with a Location header telling it where it should make the new request to.

  • http-request set-path (HAProxy rule) – Incoming URLs matching the condition (if one is specified) are rewritten before making the request to the backend hosting the new path, without telling the client about the changed URL.

  • http-request reject – Returns a 403 status code to the client by default, but deny_status can be specified to return any desired status code. The request will not be sent to the backend.

  • http-request return –  Returns a response with a custom body and status code. For example, this may include a page telling the client why their request was denied, serving an empty page, or otherwise. 

You can also rewrite the HTTP header itself using multiple directives. Each accepts log format directives so a regex can be applied to a Location header with something like %[res.hdr(location),regsub(/images,/static/images)]. Here are some examples: 

  • http-request/http-response set-header – Replaces a header value in the HTTP request or response with the specified value, removing any matching headers sent by the client or backend

  • http-request/http-response add-header – Adds one or more headers to the HTTP request or response

  • http-request/http-response del-header – Removes one or more headers from the HTTP request or response

Most of these rules will work like CSS rules, where each one will modify their part of the request. However, some directives such as http-request redirect/deny/return stop processing rules and return a specified response to the client.

You’ve mastered one topic, but why stop there?

Our blog delivers the expert insights, industry analysis, and helpful tips you need to build resilient, high-performance services.

By clicking "Get new posts first" above, you confirm your agreement for HAProxy to store and processes your personal data in accordance with its updated Privacy Policy, which we encourage you to review.

Thank you! Your submission was successful.

Does HAProxy support HTTP rewrites?

Yes! HAProxy and HAProxy One use http-request and http-response configuration directives to rewrite requests and responses. HAProxy enables you to set, add, delete, and replace HTTP headers — including URL paths and URIs — and much more to alter requests and responses. 

To learn more about HTTP rewrites, check out our HTTP rewrites documentation.