Getting Started with API Migration - Editor

Create a project

Run:

Code
npx create-zuplo-api@latest migrated-api
cd migrated-api

When prompted, choose Yes to create a matching Portal project, then complete sign-in and account selection to link your local copy. For an existing project, work on a new Git branch before importing routes.

Get your existing OpenAPI document

Get your API's OpenAPI document from its repository, API documentation, or current gateway. Save a copy in the project root. The commands below use openapi.json; substitute your file's name if it differs.

If you don't have an OpenAPI document, download the

.

Choose a read-only operation and call it directly on the original API. Record its URL, required headers, query parameters, and response. For Petstore, try:

Code
curl -i "https://petstore3.swagger.io/api/v3/pet/findByStatus?status=available"

Import the routes

Run:

Code
npx zuplo openapi merge --source ./openapi.json --destination ./config/routes.oas.json

Open config/routes.oas.json and find the operation you chose. The destination must end in .oas.json. See openapi merge for importing from URLs and controlling server paths.

Configure forwarding

On the operation you chose, set x-zuplo-route to the following, replacing YOUR_UPSTREAM_BASE_URL with your original API's base URL:

Code
"x-zuplo-route": {
  "corsPolicy": "none",
  "handler": {
    "module": "$import(@zuplo/runtime)",
    "export": "urlForwardHandler",
    "options": { "baseUrl": "YOUR_UPSTREAM_BASE_URL" }
  },
  "policies": { "inbound": [] }
}

Importing OpenAPI describes the route; this handler makes it forward to the upstream. See URL Forward. Check the imported path so any server prefix appears only once. For Petstore, use https://petstore3.swagger.io/api/v3 if the route path is /pet/findByStatus, or https://petstore3.swagger.io if it already starts with /api/v3.

Compare local and upstream responses

Start npm run dev. In a second terminal, run:

Code
curl -i "http://localhost:9000/YOUR_ROUTE"

Replace YOUR_ROUTE with the imported route path. Include the same headers and query parameters as your original request, such as status=available for Petstore. Compare the status and response structure with the original API; live data can change between requests. Check the gateway logs if you get an error.

Preserve behavior when importing updates

Before re-importing a changed OpenAPI file, commit your work. Run the same merge command and review git diff. The importer merges routes by path and method and preserves Zuplo route configuration. Routes absent from the new document aren't automatically deleted; review them explicitly.

For your own API, translate authentication, rate limits, and transformations into Zuplo policies. OpenAPI security declarations don't enforce access control. Test both allowed and rejected requests, plus the headers, query parameters, and bodies your clients send. The migration overview covers existing gateway configurations.

Deploy and move a test client

Follow Deploy to the edge, then repeat your tests against the deployed gateway URL. Change one test client's base URL to that gateway and verify its workflow before moving more clients. Keep the original endpoint available for rollback.