# Getting Started with API Migration - Editor

<WizardSteps build="migrate" method="local" />

<MethodTabs build="migrate" method="local" />

Import an existing API into a local Zuplo project, add its upstream handler, and
compare responses before moving client traffic.

## Prerequisites

- [Node.js](https://nodejs.org/en/download) 24 or later and Git.
- A terminal and an editor.
- A [Zuplo account](https://portal.zuplo.com) for linking and deployment.

## Import and test your API

<Stepper>

1. **Create a project**

   Run:

   ```bash
   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.

2. **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.

   <p>
     If you don't have an OpenAPI document, download the{" "}
     <a href="/docs/downloads/petstore-openapi.json" download="openapi.json">
       Swagger Petstore OpenAPI document
     </a>
     .
   </p>

   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:

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

3. **Import the routes**

   Run:

   ```bash
   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`](../../cli/openapi-merge.mdx) for importing from URLs and
   controlling server paths.

4. **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:

   ```json
   "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](../../handlers/url-forward.mdx). 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`.

5. **Compare local and upstream responses**

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

   ```bash
   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.

6. **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](../../articles/migration-overview.md) covers existing
   gateway configurations.

7. **Deploy and move a test client**

   Follow [Deploy to the edge](../gateway/deploy-to-the-edge/local.mdx), 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.

</Stepper>

## Next steps

- [Add API key authentication](../gateway/add-api-key-auth/local.mdx).
- [Configure upstream AWS authentication](../../articles/upstream-iam-auth.mdx).
- [Plan your full migration](../../articles/migration-overview.md).