Redirect vs URL rewrite in an API gateway

01-21-2025: We updated this blog post with updates to Traffic Policy phases and an additional use case for redirects/rewrites using cloud endpoints.

ngrok’s Traffic Policy engine, which allows you to utilize ngrok as an API gateway, boasts a variety of actions that can be taken at the gateway level to enable you to modify the behavior of traffic flowing through your endpoints. Actions such as adding headers, compressing responses, and JWT validation are some more straightforward examples that need little explanation about what they do. However, what’s the difference between actions like URL rewriting and redirection?

A common use case for considering either of these actions is when migrating to a new version of an API. In my case, I have an API running at https://api.ngrokpaperscissors.com with all of my original endpoints in a directory called /v1/. Those endpoints are expecting a query string that includes parameters for accountId and active. However, the next version of the API will be getting the accountId in a different way, so that parameter is no longer needed. I’m ready to migrate incoming traffic from the v1 directory to the new code now running in the /v2/ directory. Rather than ask all of the users of my API to change their code to access the new /v2/ endpoints and manually remove the accountId query parameter, I can configure ngrok’s Traffic Policy engine to automatically route traffic to the new services with the correct parameters.

Looking at the Traffic Policy documentation, I see two actions appear to route traffic for me: redirect and url-rewrite. But which do I use?

In this blog post, I’ll explore these two actions, how to best use them, and answer the question of when to use them. First, I’ll look at redirect.

Tip: If this is your first time hearing about ngrok's Traffic Policy engine, take a moment to read up on how it works in our developer docs or explore the "why" in our announcement post.

Redirect

The redirect action enables incoming requests to be redirected to new URLs by modifying the original URLs with regular expressions. This redirection is done by setting the Location header of the response, requiring the client to make a second API call to the URL specified in that header.

For example, when I create a redirect action in my Traffic Policy configuration, the expression would look something like this:

---
on_http_request:
  - actions:
      - type: redirect
        config:
          from: /v1/(.+)\?(.+)
          to: /v2/$1?active=true
    name: API Route Migration Redirect

The expression takes all requests calling /v1/ endpoints and redirects them to the corresponding endpoint in the /v2/ directory of the API. The expression also adds a active=true query string parameter, which is needed by the endpoints.

When a client makes a request to the following API endpoint https://api.ngrokpaperscissors.com/v1/list, the request is redirected to https://api.ngrokpaperscissors.com/v2/list?active=true.

Using a command line utility like HTTPie the request would look something like this:

% http 'https://api.ngrokpaperscissors.com/v1/list?accountId=12345&active=true'
HTTP/1.1 302 Found
Content-Length: 0
Date: Thu, 08 Aug 2024 01:46:25 GMT
Location: https://api.ngrokpaperscissors.com/v2/list?active=true

The GET request went to https://api.ngrokpaperscissors.com/v1/list, and the ngrok API gateway returned a 302 status response along with the redirect URL as part of the Location header. It’s up to the client making the call to decide how to handle the redirect. Most of the time, the client will need to make a second call to the new URL. However, if this call were done in a web browser by default the browser would likely make the second call and open the new page automatically.

Redirect considerations

A redirect response also allows me, as the API owner, to communicate additional information to the client through HTTP status codes. For instance, the request shown above returned a very general 302, which tells the client the request was Found. It’s also the default response code that ngrok returns for the redirect action. It’s much more helpful to clients if a more specific status code is returned.

The most common actions to communicate to the client are whether the redirection is a permanent or temporary change. If this is a permanent redirect, I would return a 301 status code which communicates a Moved Permanently message. If the change is only temporary, I could keep the default 302 or use 307, which is specifically used to communicate this is a Temporary Redirect.

In this case, I’ll communicate that the redirect is permanent by setting the status_code: 301 in the config object of my Traffic Policy action, like this:

---
on_http_request:
  - actions:
      - type: redirect
        config:
          status_code: 301
          from: /v1/(.+)\?(.+)
          to: /v2/$1?active=true
    name: API Route Migration Redirect

URL rewrite

URL rewriting looks very similar to redirects, except it provides a slightly more subtle user experience. Rather than modifying the URL of the request at the client level, a URL rewrite modifies the URL before the request reaches the upstream server. The client will receive no indication that the URL was modified.

As an example, I’ll change my existing API Route Migration expression to be a url-rewrite action. To do that, all I’ll need to do is change the value of type to url-rewrite and remove the status_code since the action doesn’t allow for setting the status_code. The YAML will now look like this:

---
on_http_request:
  - name: API Route Migration Rewrite
    actions:
      - type: url-rewrite
        config:
          from: /v1/(.+)\?(.+)
          to: /v2/$1?active=true

Now when I make a call to an endpoint in the /v1/ directory, the response is sent from the /v2/ endpoint. In the example below, the list endpoint returns a JSON object of all the requests received by that endpoint. Notice the requested URL was /v1/list?accountId=12345&active=true, but the JSON response shows that /v2/list processed the request and sent a response with a 200 status code.

% http 'https://api.ngrokpaperscissors.com/v1/list?accountId=12345&active=true'
HTTP/1.1 200 OK
Content-Length: 60
Content-Type: application/json; charset=utf-8
Date: Thu, 08 Aug 2024 00:48:57 GMT
X-Powered-By: Express

{
    "requests": [
        {
            "method": "GET",
            "url": "/v2/list?active=true"
        }
    ]
}

When to use one or the other

In situations where the clients and users need to be notified of changes to the endpoint URLs, it’s appropriate to use redirects with the corresponding HTTP status code. API consumers then have the choice to check for those 300-level status codes and act on any Location headers that are passed. Making additional calls to the API for a redirect may seem less efficient. However, extra processing may be necessary to inform the clients of changes.

If there’s no reason for the client to know the location of new backend services at new endpoints, then url-rewrite may be the way to go. The client's user experience is seamless as the services change, as long as the data returned by the new service is still in a compatible format.

Use ngrok for 'serverless' redirects and rewrites

One common problem for DevOps and infrastructure engineers is that to support frontend engineers, technical writers in documentation, or even marketing teams, they must establish and maintain a separate webserver just for redirects and rewrites.

Or use something even more fragile, like IFTTT.

Instead, you could create a single cloud endpoint on your root domain and use the Traffic Policy actions detailed earlier to establish these routes using composable patterns. Because cloud endpoints are not tied to the lifecycle of an ngrok agent—they effectively behave like serverless functions—you don't need to maintain any additional infrastructure, and you only pay for what you use.

For an example of how you might architect this using cloud and internal endpoints, see our blog post on creating a self-service platform for developers.

Learn more about ngrok and our Traffic Policy engine

URL rewrite and redirection are just two of the many actions you can configure in your API gateway powered by our composable Traffic Policy engine. To learn more about Traffic Policy, take a look at these resources:

• Traffic Policy developer docs
• "API gateway" gallery: Drop-in API policy management examples
• Traffic Policy Engine - What are CEL variables?

All you need to get started is a free ngrok account and an endpoint.

Questions about using rewrites and redirects? Want to beam over a feature request? Join us on our monthly Office Hours livestreams or drop an issue in our ngrok/ngrok community repo on GitHub.