Redirect Handler

The Redirect Handler sends a redirect HTTP response to the client. Use it to redirect traffic from one URL to another, such as directing users from a deprecated endpoint to its replacement or redirecting a root path to documentation.

Setup via Portal

The Redirect Handler can be added to any route using the Route Designer. Open the Route Designer by navigating to the Code tab then click routes.oas.json. Inside any route, select Redirect from the Request Handlers drop-down.

In the text box enter the URL location for the redirect.

Setup in routes.oas.json

Configure the Redirect Handler directly in the routes.oas.json file. The following example redirects requests at the root of a domain to a docs page at /docs:

Code
"paths": {
  "/redirect-test": {
    "x-zuplo-path": {
      "pathMode": "open-api"
    },
    "get": {
      "summary": "Testing rewrite handler",
      "x-zuplo-route": {
        "corsPolicy": "none",
        "handler": {
          "module": "$import(@zuplo/runtime)",
          "export": "redirectHandler",
          "options": {
            "location": "/docs"
          }
        }
      },
      "policies": {
        "inbound": []
      }
    }
  }
}

Options

The Redirect Handler accepts the following options:

• location (required): The URL or path to redirect the client to.

  • Type: string
  • Supports absolute URLs (e.g., https://example.com/docs) and relative paths (e.g., /docs)

• status (optional): The HTTP status code for the redirect response.

  • Type: number
  • Default: 302
  • Common values:
    • 301 - Permanent redirect. Browsers and search engines cache this redirect. Use for endpoints that have permanently moved.
    • 302 - Temporary redirect (default). The client should continue using the original URL for future requests.
    • 307 - Temporary redirect that preserves the HTTP method. Unlike 302, the client must use the same method (POST, PUT, etc.) when following the redirect.
    • 308 - Permanent redirect that preserves the HTTP method. Like 301, but the client must use the same method when following the redirect.

Examples

Permanent redirect to an external URL:

Code
{
  "handler": {
    "module": "$import(@zuplo/runtime)",
    "export": "redirectHandler",
    "options": {
      "location": "https://newapi.example.com/v2",
      "status": 301
    }
  }
}

Temporary redirect preserving the HTTP method:

Code
{
  "handler": {
    "module": "$import(@zuplo/runtime)",
    "export": "redirectHandler",
    "options": {
      "location": "/maintenance",
      "status": 307
    }
  }
}

Common Use Cases

• API versioning: Redirect requests from an old API version to the current version using a 301 permanent redirect.
• Documentation entry point: Redirect the root path (/) to a documentation page or developer portal.
• Deprecated endpoints: Redirect traffic from removed endpoints to their replacements.
• Domain migration: Redirect requests from a legacy domain to a new domain.