Legacy Dev Portal Handler

Copy page

The Legacy Dev Portal Handler helps you maintain compatibility with the legacy developer portal after migrating to the new Zudoku-based developer portal. It supports two modes of operation: redirect mode and proxy mode.

What It Does

When you migrate from the legacy developer portal to the new Zudoku-based portal, the new portal runs on its own dedicated domain (e.g., docs.example.com) instead of under a path on your API domain (e.g., api.example.com/docs). The Legacy Dev Portal Handler ensures that users who navigate to the old /docs path are either redirected to the new domain or can continue accessing the portal from the same path.

Redirect Mode (Recommended)

In redirect mode, the handler redirects all requests from the legacy path (e.g., /docs*) to the new developer portal domain. This is the recommended approach as it provides better performance and usability.

Setup

1. Create a Route: In your routes.oas.json file (or create a new OpenAPI file like legacy.oas.json), add a route that matches the legacy path:

Code
 
{
  "openapi": "3.1.0",
  "info": {
    "version": "1.0.0",
    "title": "Dev Portal Redirect"
  },
  "paths": {
    "/docs(.*)": {
      "x-zuplo-path": {
        "pathMode": "url-pattern"
      },
      "get": {
        "summary": "Redirect to new Dev Portal",
        "description": "Redirect requests from legacy /docs path to the new Dev Portal domain",
        "x-zuplo-route": {
          "corsPolicy": "none",
          "handler": {
            "export": "legacyDevPortalHandler",
            "module": "$import(@zuplo/runtime)",
            "options": {
              "mode": "redirect"
            }
          },
          "policies": {
            "inbound": []
          }
        },
        "operationId": "dev-portal-redirect"
      }
    }
  }
}

Custom Domain

By default, the handler redirects to your project's default Zuplo domain (e.g., my-project-1a3ksl3.zuplo.site). If you've set up a custom domain for your developer portal, the handler will automatically use the custom domain instead.

Learn more about setting up custom domains in the Custom Domains documentation.

Proxy Mode

In proxy mode, the handler proxies requests from the API domain path (e.g., /docs*) to the developer portal, allowing the portal to be served from the same domain as your API. This approach is not recommended for performance and usability reasons, but is available if you need to keep the developer portal on the same domain.

Setup

1. Configure the Handler: Update your route configuration to use proxy mode:

Code
 
{
  "handler": {
    "export": "legacyDevPortalHandler",
    "module": "$import(@zuplo/runtime)",
    "options": {
      "mode": "proxy"
    }
  }
}

2. Configure Zudoku Base Path: In your docs/zudoku.config.ts file, set the basePath to match the path where your portal will be served:

Code
 
import type { ZudokuConfig } from "zudoku";

const config: ZudokuConfig = {
  basePath: "/docs",
  site: {
    title: "My API Documentation",
  },
  // ... rest of your configuration
};

export default config;

With this configuration, your developer portal will continue to be accessible at https://api.example.com/docs just as it was with the legacy developer portal.

Migration Guide

For complete instructions on migrating from the legacy developer portal to Zudoku, see the Dev Portal Migration Guide.