How to Rewrite URL Parameters in NGINX

NGINX rewrite rules allow you to redirect users from one URL to another. They are a very important way of informing the users that the requested resource has moved. Website administrators need to regularly redirect users from one URL to another, in case the website is re-organized. In this article, we will learn why you need to rewrite URL parameters in NGINX and the different ways to do this.

Why Rewrite URL Parameters

There are several reasons why you may need to rewrite URL in NGINX. Here are some of the common reasons:

1. Website restructuring – Often site administrators and web developers need to re-organize web pages on their site to make it easier to browse for users and crawl for search engines. In such cases, you will need to rewrite URL parameters to redirect users from old pages to new pages.
2. Moving web pages – Sometimes you genuinely need to move one or more web pages from one location to another. In such cases, you need to rewrite URL along with its parameters.
3. Remove Outdated content – If your site is content-heavy with regularly published content, then over time, some of it may become outdated. In such cases, you may need to rewrite a fresh piece on the topic and redirect old URL to new one.
4. URL structure change – Sometimes, the entire structure of your website’s URL needs to be changed to make it more intuitive for both users and search engines. In such cases, you need to rewrite URL parameters in NGINX.

Return vs Redirect Directive

NGINX provides two ways to rewrite URL parameters in NGINX – return statement and rewrite statement. It is important to understand them properly before we proceed.

Return Directive

The Return directive stops processing the request and returns a specific response code (e.g. 301, 302) along with the new URL, to the client web browser. Then the client browser sends another request to this new URL. This is how URL redirection occurs with return directive. Since the browser needs to make a separate request to new URL, the URL in address bar changes.

Return statement is useful for simple use cases such as forcing HTTP to HTTPS or completely migrating website to a new domain. For more complex use cases, you need to use Return directive.

Rewrite Directive

In case of rewrite directive, the redirection happens internally in the server. Here the server will perform redirection and return response code along with the new page’s contents to the client browser. So the redirection happens without changing the address bar URL.

Rewrite statement is used for complex scenarios such as where you need to perform regular expression matching to extract a part of original URL. Other use cases involve using multiple rewrite statements within the same context, or creating pretty links for ugly URLs in content management system or E-commerce site.

How to Rewrite URL Parameters in NGINX

Let us look at the steps to rewrite URL parameters in NGINX.

Using Rewrite

You can use rewrite directive to easily rewrite URL parameters, using regular expressions and back references. Here is the syntax for rewrite directive.

rewrite regex replacement-url [flag];

In the above directive,
regex – regular expression used to match requested URL
replacement-url – the new url string to be used for matching requests
flag – decides whether to process further rewrite requests or not

You can place this directive in server or location blocks. Let us look at two use cases – where we redirect from parameter-based URL to a path-based URL and vice versa.

Rewrite from parameter-based URL to path-based URL

Let us say you want to redirect /product.php?id=4 to /product/4

In the above case, we use regular expression along with parameter name to capture parameter value. So place the following line in server or location block.

location = /product.php {
    rewrite ^/product\.php\?id=(\d+)$ /user/$1 permanent
}

Let us look at the above code in detail.

^ – beginning with
$ – ending with
\d+ – match one or more digits
(\d+) – capture digits using back reference
$1 – uses value of first group
permanent – permanent redirection, HTTP response code 301

Rewrite from path-based URL to parameter-based URL

Let us say you want to redirect from /product/4 to product.php?id=4

In this case, we use regular expression to capture path segments and use them as parameters in URL. For this purpose, add the following rewrite directive in location block as shown.

location /product/ {
    rewrite ^/product/(\d+)/?$ /product.php?id=$1 last
}

Let us look at the above code in detail.

$1 – captured parameter
^ – beginning with
$ – ending with
(\d+) – digits in URL path after /product/
last – stops processing rewrite directives and redirect to new location

If you want to remove all parameters from URL, then use the following rewrite directive.

rewrite ^/old-path /new-path? permanent;

Using Return

Return directive is useful to implement simple redirects. Here is its syntax.

return response_code old-url new-url;

For example, let us say you want to redirect a group of parameter-based URLs to a single page, then you can simply use return directive. Let us say you want to return parameterized pages to /product.php (/product.php?id=11, /product.php?id=12, etc) to /products. You can easily do this using return statement as shown.

location = /product.php {
    return 301 $scheme://example.com/products
}

In the above code, the location block will match all parameterized URLs starting with /product.php. Then it returns them to /products page.

Conclusion

In this article, we have learnt why you need to redirect users on your website. We have also learnt how to implement this in NGINX – using return and rewrite statements. We have learnt about the difference between return and rewrite statement. Depending on your requirement, you can use any of the methods described above.

FAQs

1. When to use Rewrite Statement
Rewrite statement is useful to match one or more URLs, fetch their URL parameters and redirect them to path-based URLs created using the parameter values. On the other hand, it is also useful to extract path values from path-based URLs and redirect them to parameter-based URLs created using the path values.

2. When to use Return Statement
Return statement is useful when you need to migrate all or most of your web pages to a new location. It is also useful for canonicalization of similar URLs. You can also use it where you just need to simply redirect a bunch of known URLs to a single page.

Also Read:
How to Redirect Location to Another Domain
How to Configure Multiple Host Names in NGINX
How to Increase File Upload Size in NGINX