# Getting Started with API Migration - Portal

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

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

Put Zuplo in front of an existing API by importing its OpenAPI document and
forwarding requests to the original backend. You'll test one read-only route
before changing any client traffic.

## Prerequisites

- A [Zuplo account](https://portal.zuplo.com).
- Your existing API's OpenAPI document in JSON or YAML and its upstream URL.

## Get your existing OpenAPI document

Get the OpenAPI document for the API you want to migrate from its repository,
API documentation, or current gateway. Download or export the existing file; you
don't need to write a new one for this tutorial.

<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. You'll
compare that response with the gateway's response. For Petstore, you can use
[`GET /pet/findByStatus?status=available`](https://petstore3.swagger.io/api/v3/pet/findByStatus?status=available).

## Import and test a route

<Stepper>

1. **Create the gateway**

   In [**Projects**](https://portal.zuplo.com/+/account/projects), click **New
   Project**, select **API & MCP Gateway**, enter `migrated-api`, and click
   **Create Project**.

2. **Import the document**

   Open **Code → config/routes.oas.json** and click **Import OpenAPI**. Upload
   your OpenAPI file, review the routes, and click **Complete Import**.

   <ModalScreenshot>

   ![Import an OpenAPI file in the Route Designer](/media/mcp-quickstart/import-openapi.png)

   </ModalScreenshot>

   The Route Designer should now list your API's routes. Importing an API
   description doesn't configure its forwarding behavior or enforce its security
   requirements; configure those next.

3. **Set the upstream handler**

   Select the read-only route you chose. Under **Request Handler**, select **URL
   Forward** and set **Forward to** to your original API's base URL. Save your
   changes.

   The [URL Forward handler](../../handlers/url-forward.mdx) appends the request
   path. Check the imported path before setting the base URL so that 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 the imported path
   already starts with `/api/v3`.

4. **Compare the response**

   Click **Test** next to the route's path, then send a GET request. Expect the
   same status and response structure as the original API. Include the same
   query parameters, such as `status=available` for the Petstore example.

   Copy the gateway request URL from the test dialog and call it from a terminal
   too:

   ```bash
   curl -i "https://YOUR_GATEWAY.zuplo.app/YOUR_ROUTE"
   ```

   Replace `YOUR_ROUTE` with the imported route path and include its query
   parameters and any required headers. A `404` usually means the route or
   upstream path differs from the imported path. If forwarding fails, recheck
   the handler's upstream URL.

5. **Preserve your API's behavior**

   For a private API, add the
   [authentication policies](../../articles/api-key-authentication.mdx) your
   clients require and configure any credentials the upstream requires. OpenAPI
   `security` metadata alone doesn't enforce authentication in Zuplo.

   Before migrating real traffic, verify successful and failed requests, query
   parameters, headers, request bodies, and status codes. Recreate any rate
   limits or transformations currently handled by your old gateway. See the
   [migration overview](../../articles/migration-overview.md) for
   platform-specific migration guides.

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

   Follow [Deploy to the edge](../gateway/deploy-to-the-edge/index.mdx) to
   connect source control and deploy. Repeat your tests using the deployed
   gateway URL.

   Change one test client's base URL to the gateway and verify its normal
   workflow. Keep the old endpoint available while you move clients in stages;
   roll that client back to its previous base URL if checks fail. Move your
   production domain only after the gateway passes your migration checks.

</Stepper>

## Next steps

- [Add API key authentication](../gateway/add-api-key-auth/index.mdx).
- [Import updated OpenAPI documents](../../articles/openapi.mdx).
- [Plan a migration from another gateway](../../articles/migration-overview.md).