zuplo 6.67.32 → 6.68.0

package/docs/articles/source-control.mdx

@@ -0,0 +1,80 @@
+---
+title: Source Control & Deployments
+sidebar_label: Overview
+---
+
+Zuplo integrates with your Git repository for both development and deployments.
+Understanding how these work together helps you choose the right setup for your
+team.
+
+## Two Capabilities, One Integration
+
+**Source control integration** gives you push/pull access between the Zuplo
+portal and your repository. Edit in the portal, commit to Git. Pull changes from
+teammates. This works with GitHub, GitLab, Bitbucket, and Azure DevOps.
+
+**Automatic deployments** trigger a deploy every time you push to your
+repository. Push to `main` and your production environment updates. Push to a
+feature branch and get an isolated preview environment. This is currently
+GitHub-only.
+
+## Choosing Your Setup
+
+### GitHub (Recommended)
+
+GitHub provides the most complete experience:
+
+- **Source control** — Push and pull between portal and repository
+- **Automatic deployments** — Every push deploys automatically
+- **Branch environments** — Each branch gets its own environment
+- **Deployment status** — See deploy results directly in GitHub
+
+For most teams, the default GitHub integration handles everything. You can add
+[deployment testing](./github-deployment-testing.mdx) to run your test suite
+after each deploy without any custom CI/CD.
+
+If you need approval gates, complex test pipelines, or tag-based releases, see
+[Custom GitHub Actions](./custom-ci-cd-github.mdx).
+
+**[Set up GitHub →](./source-control-setup-github.mdx)**
+
+### GitLab, Bitbucket, Azure DevOps (Enterprise)
+
+These providers offer source control integration on
+[enterprise plans](https://zuplo.com/pricing):
+
+- **Source control** — Push and pull between portal and repository
+- **No automatic deployments** — Use CI/CD pipelines to deploy
+
+Since these providers don't have automatic deployments, you'll use their native
+CI/CD systems to deploy via the Zuplo CLI.
+
+- **[GitLab setup](./source-control-setup-gitlab.mdx)** and
+  [CI/CD pipelines](./custom-ci-cd-gitlab.mdx)
+- **[Bitbucket setup](./source-control-setup-bitbucket.mdx)** and
+  [CI/CD pipelines](./custom-ci-cd-bitbucket.mdx)
+- **[Azure DevOps setup](./source-control-setup-azure.mdx)** and
+  [CI/CD pipelines](./custom-ci-cd-azure.mdx)
+
+### Other CI/CD Providers
+
+If your code lives elsewhere but you want to use a specific CI/CD system:
+
+- **[CircleCI](./custom-ci-cd-circleci.mdx)** — Flexible workflows with approval
+  jobs
+
+## How Branch-Based Deployments Work
+
+Every Git branch maps to a Zuplo environment. Push to `main` and deploy to your
+main environment. Push to `feature-auth` and get a `feature-auth` environment
+automatically.
+
+This enables powerful workflows like PR preview environments where reviewers can
+test changes against a live API before merging.
+
+Learn more: [Branch-Based Deployments](./branch-based-deployments.mdx)
+
+## Managing Your Project
+
+- [Rename or Move Project](./rename-or-move-project.mdx) — How to handle
+  repository changes

package/docs/articles/step-1-setup-basic-gateway-local.mdx

@@ -0,0 +1,136 @@
+---
+title: Step 1 - Setup a Basic Gateway
+sidebar_label: "1 - Setup Your Gateway"
+---
+
+<QuickstartPicker
+  mode="local"
+  alternateLink="/articles/step-1-setup-basic-gateway"
+/>
+
+In this tutorial we'll set up a simple gateway using Zuplo's local development.
+We'll use a simple origin API at [echo.zuplo.io](https://echo.zuplo.io). In
+later steps, we'll set up a Zuplo project and deploy it to the cloud.
+
+## Requirements
+
+- [Node.js](https://nodejs.org/en/download) 20.0.0 or higher
+
+## Getting Started
+
+### Create a new project from scratch
+
+<Stepper>
+
+1. Create a new project using
+
+   ```bash
+   npx create-zuplo-api@latest --empty
+   ```
+
+   The [create-zuplo-api](../cli/create-zuplo-api.mdx) tool supports creating
+   projects from templates. This tutorial creates an empty project, but you can
+   use other [templates](https://zuplo.com/examples) by specifying the
+   `--example` flag.
+
+1. Start your local gateway
+
+   ```bash
+   cd <your-new-project-directory>
+   npm run dev
+   ```
+
+1. Use the [local Route Designer](./local-development-routes-designer.mdx) to
+   create your first route. You can open the Route Designer by clicking the link
+   in the terminal after you run `npm run dev`.
+
+   ```bash
+   Started local development setup
+   Ctrl+C to exit
+
+   🚀 Zuplo Gateway: http://localhost:9000
+   📘 Route Designer: http://localhost:9100 # <-- Your local route designer
+   ```
+
+1. Add your first **Route**
+
+   Inside of the Route Designer, click the **Add Route** button.
+
+   ![Add Route](../../public/media/step-1-setup-basic-gateway-local/image.png)
+
+   Your API's first route will appear, with many options. First we'll configure
+   the route to match specific incoming requests to the gateway:
+   - **Summary**: Enter a summary, for example `Example Endpoint`.
+   - **Method**: Leave as `GET`.
+   - **Path**: The path will be pre-configured as `path-1`.
+   - **Operation ID**: Pre-configured based on the path summary.
+
+   Then we'll specify how the route will invoke the backend origin API, using a
+   forward handler:
+   - **Request Handler**: We'll use the
+     [URL Forward Handler](../handlers/url-forward.mdx) which proxies requests
+     by "Forwarding to" the same path on specified URL. In this case, enter
+     `https://echo.zuplo.io`
+
+     ![Your First Route](../../public/media/step-1-setup-basic-gateway-local/image-1.png)
+
+   **Save your changes** - click **Save** in the bottom left, or press **CMD+S**
+
+1. **Test** your route
+
+   You can test this route by clicking the **Test Route** button in the route
+   designer.
+
+   ![Testing in the Route Designer](../../public/media/step-1-setup-basic-gateway-local/test.png)
+
+   Alternatively, you can test the route in your favorite HTTP Client (for
+   example Postman, HTTPie, curl, etc).
+
+   ```bash
+   curl http://localhost:9000/0
+
+   {
+      "url": "https://echo.zuplo.io/path-1",
+      "method": "GET",
+      "query": {},
+      "headers": {
+         "accept-encoding": "gzip, br",
+         "connection": "Keep-Alive",
+         "host": "echo.zuplo.io",
+         "true-client-ip": "2a06:98c0:3600::103",
+         "x-forwarded-proto": "https",
+         "x-real-ip": "2a06:98c0:3600::103",
+         "zp-rid": "b9822e0f-af32-4002-a6ba-3a899c7f2669",
+         "zuplo-request-id": "b9822e0f-af32-4002-a6ba-3a899c7f2669"
+      }
+   }
+   ```
+
+1. Now that you have a simple gateway running, we can deploy it to the cloud
+   using the [Zuplo CLI](../cli/overview.mdx). When you run this command, you
+   will be prompted to login if you haven't already.
+
+   If you haven't already created a Zuplo project, you will be prompted to do
+   so. If you do have a project, you can choose to deploy to it or you can
+   specify the `--project` flag to specify the project you want to deploy to.
+
+   ```bash
+   npx zuplo deploy
+   ```
+
+   You should see output similar to this:
+
+   ```bash
+   ? You don't have any projects configured for this account.
+     Enter the name of the new project: my-tutorial
+   ✔ Project my-tutorial created successfully.
+   ✔ Deployed to https://my-tutorial-main-11686c3.zuplo.app (93/150)
+   ```
+
+   Your project is now deployed to the cloud and you can access it at the URL
+   provided in the output.
+
+</Stepper>
+
+**NEXT** Try
+[Step 2 - Add Rate Limiting to your API](./step-2-add-rate-limiting-local.mdx).

package/docs/articles/step-1-setup-basic-gateway.mdx

@@ -0,0 +1,118 @@
+---
+title: Step 1 - Setup a Basic Gateway
+sidebar_label: "1 - Setup Your Gateway"
+---
+
+<QuickstartPicker
+  mode="portal"
+  alternateLink="/articles/step-1-setup-basic-gateway-local"
+/>
+
+In this tutorial we'll set up a simple gateway. We'll use a simple origin API at
+[getting-started.zuplo.io](https://getting-started.zuplo.io).
+
+Note - Zuplo also supports building and running your API locally. To learn more
+[see the documentation](./local-development.mdx).
+
+<Stepper>
+
+1. **Sign-in**
+
+   Sign in to [portal.zuplo.com](https://portal.zuplo.com) and create a free
+   account. Create a new **empty** project (don't import an existing project,
+   we'll set up git later). Then...
+
+1. Add your first **Route**
+
+   Inside your new project, select the **Code** tab (1), choose the
+   `routes.oas.json` file (2) and click **Add Route** (3)
+
+   ![Add Route](../../public/media/step-1-setup-basic-gateway/add-route.png)
+
+   Your API's first route will appear, with many options. First we'll configure
+   the route to match specific incoming requests to the gateway:
+   - **Summary**: Enter a summary, for example `Example Endpoint`.
+   - **Method**: Leave as `GET`.
+   - **Path**: Enter `path-0`.
+
+   Then we'll specify how the route will invoke the backend origin API, using a
+   forward handler:
+   - **Request Handler**: We'll use the
+     [URL Forward Handler](../handlers/url-forward.mdx) which proxies requests
+     by "Forwarding to" the same path on specified URL. In this case, enter
+     `https://echo.zuplo.io`
+
+   ![Your First Route](../../public/media/step-1-setup-basic-gateway/image-14.png)
+
+   **Save your changes** - click **Save** at the bottom left, or press **CMD+S**
+
+1. **Test** your route.
+
+   You can quickly test this route by clicking the **Test** button next to the
+   **Path** field. You can use the built in test tool or click the URL to open
+   in a new tab.
+
+   <ModalScreenshot>
+
+   ![Test your API](../../public/media/step-1-setup-basic-gateway/image-15.png)
+
+   </ModalScreenshot>
+
+   You should receive a 200 OK that says something similar to
+
+   ```json
+   {
+     "url": "https://echo.zuplo.io/path-0",
+     "method": "GET",
+     "query": {},
+     "headers": {
+       "accept-encoding": "gzip, br",
+       "connection": "Keep-Alive",
+       "host": "echo.zuplo.io",
+       "true-client-ip": "2a06:98c0:3600::103",
+       "x-forwarded-proto": "https",
+       "x-real-ip": "2a06:98c0:3600::103",
+       "zp-rid": "b9822e0f-af32-4002-a6ba-3a899c7f2669",
+       "zuplo-request-id": "b9822e0f-af32-4002-a6ba-3a899c7f2669"
+     }
+   }
+   ```
+
+   A secret? Let's try and find out what this API is hiding!
+
+1. Put the base URL in an **Environment Variable**
+
+   When working with Zuplo, you'll eventually want each
+   [environment](/docs/articles/environments) to use a different backend (for
+   example QA, staging, preview, production etc).
+
+   Change the **URL Forward** value to read the base URL from the
+   [Environment Variables](/docs/articles/environment-variables) system by
+   setting the value to `${env.BASE_URL}`. We will set the value for `BASE_URL`
+   next.
+
+   ![BASE_URL from Environment](../../public/media/step-1-setup-basic-gateway/image-8.png)
+
+   Navigate to your project's **Settings** (1) via the navigation bar. Next,
+   click **Environment Variables** (2) under Project Settings.
+
+   ![Click Environment Variables](../../public/media/step-1-setup-basic-gateway/set-env-var.png)
+
+   Add an Environment Variable (3) called `BASE_URL`. Leave the "Secret"
+   checkbox unchecked. This is typically not a secret, so there's no need to
+   hide this from your colleagues.
+
+   <ModalScreenshot>
+
+   ![BASE_URL Environment Variable](../../public/media/step-1-setup-basic-gateway/env-var.png)
+
+   </ModalScreenshot>
+
+   Save the environment variable, head back to the **Code** tab, click
+   `routes.oas.json`, and test your route again. You should get back the same
+   response from Step 2.
+
+</Stepper>
+
+**NEXT** Try
+[Step 2 - Add Rate Limiting to your API](./step-2-add-rate-limiting.mdx).

package/docs/articles/step-2-add-rate-limiting-local.mdx

@@ -0,0 +1,126 @@
+---
+title: Step 2 - Add Rate Limiting
+sidebar_label: "2 - Rate Limiting"
+---
+
+<QuickstartPicker
+  mode="local"
+  alternateLink="/articles/step-2-add-rate-limiting"
+/>
+
+In this guide we'll add simple Rate Limiting to a route. If you don't have one
+ready, complete [Step 1](./step-1-setup-basic-gateway-local.mdx) first.
+
+Rate Limiting is one of our most popular **policies** - you should never ship an
+API without rate limiting because your customers or internal developers **will**
+accidentally DoS your API; usually with a rogue `useEffect` call in React code.
+
+:::info{title="What's a Policy?"}
+
+[Policies](./policies.mdx) are modules that can intercept and transform an
+incoming request or outgoing response. Zuplo offers a wide range of policies
+built-in (including rate limiting) to save you time. You can check out
+[the full list](./policies.mdx).
+
+:::
+
+Zuplo offers a programmable approach to rate limiting that allows you to vary
+how rate limiting is applied for each customer, or request.s
+
+In this example, we'll add a simple IP based rate limiter, but you should look
+into dynamic rate limiting to see the full power of the world's best rate
+limiter.
+
+<Stepper>
+
+1.  Link your Local Project
+
+    When developing locally with Zuplo, you can "link" your local project to
+    your Zuplo project using the `zuplo link` command. This allows you to test
+    your changes in a real environment.
+
+    When you run the command you will be prompted to select your Zuplo account,
+    project, and environment. You can pick any environment.
+
+    ```bash
+    npx zuplo link
+    ```
+
+    After your project is linked, environment variables and other configuration
+    from your Zuplo project will be available in your local development
+    environment.
+
+1.  Start your Project
+
+    You can start your project using the following command:
+
+    ```bash
+    npx zuplo dev
+    ```
+
+    After your project is started, you can open the local route designer at
+    http://localhost:9100.
+
+1.  Add the rate-limiting Policy
+
+    Open the local **Route Designer** by navigating to http://localhost:9100/.
+    Select your route and click **Add Policy** on the incoming Request policies
+    section.
+
+    <BrowserScreenshot url="http://localhost:9100/?path=routes.oas.json">
+
+    ![Add Policy](../../public/media/step-2-add-rate-limiting-local/image.png)
+
+    </BrowserScreenshot>
+
+    Search for the Rate Limiting policy (not the "Complex" one) and click it.
+
+    <ModalScreenshot>
+
+    ![Add rate-limiting policy](../../public/media/step-2-add-rate-limiting/choose-rate-limiter.png)
+
+    </ModalScreenshot>
+
+    By default, the policy will rate limit based on the caller's IP address (as
+    indicated by the `rateLimitBy` field). It will allow 2 requests
+    (`requestsAllowed`) every 1 minute (`timeWindowMinutes`). You can explore
+    the rest of the policy's documentation and configuration in the right panel.
+
+    ![Rate limiting policy](../../public/media/step-2-add-rate-limiting/create-policy.png)
+
+    To apply the policy, click **Create Policy**. Then, save your changes to
+    redeploy.
+
+1.  Testing your Policy
+
+    Now try firing some requests against your API. You should receive a **429
+    Too many requests** on your 3rd request. You can use any API test tool you
+    prefer, such as Postman, HTTPie, or curl.
+
+    ```bash
+    curl http://localhost:9000/path-1
+    ```
+
+    After you make the request 3 times you will see a response similar to:
+
+    ```json
+    {
+      "type": "https://httpproblems.com/http-status/429",
+      "title": "Too Many Requests",
+      "status": 429,
+      "instance": "/path-1",
+      "trace": {
+        "timestamp": "2025-08-26T21:50:40.220Z",
+        "requestId": "4c62d425-2cb0-4a6c-9ac0-8d04a5f10c57",
+        "buildId": "f49c4070-7c0a-441b-a5fd-4e35b5fe41b7"
+      }
+    }
+    ```
+
+    Your rate limiting policy is now intercepting excess requests, protecting
+    your API.
+
+</Stepper>
+
+**NEXT** Try
+[Step 3 - Add API Key Authentication](./step-3-add-api-key-auth-local.mdx).

package/docs/articles/step-2-add-rate-limiting.mdx

@@ -0,0 +1,82 @@
+---
+title: Step 2 - Add Rate Limiting
+sidebar_label: "2 - Rate Limiting"
+---
+
+<QuickstartPicker
+  mode="portal"
+  alternateLink="/articles/step-2-add-rate-limiting-local"
+/>
+
+In this guide we'll add simple Rate Limiting to a route. If you don't have one
+ready, complete [Step 1](./step-1-setup-basic-gateway.mdx) first.
+
+Rate Limiting is one of our most popular **policies** - you should never ship an
+API without rate limiting because your customers or internal developers **will**
+accidentally DoS your API; usually with a rogue `useEffect` call in React code.
+
+:::info{title="What's a Policy?"}
+
+[Policies](./policies.mdx) are modules that can intercept and transform an
+incoming request or outgoing response. Zuplo offers a wide range of policies
+built-in (including rate limiting) to save you time. You can check out
+[the full list](../policies/overview.mdx).
+
+:::
+
+Zuplo offers a programmable approach to rate limiting that allows you to vary
+how rate limiting is applied for each customer, or requests.
+
+In this example, we'll add a simple IP based rate limiter, but you should look
+into dynamic rate limiting to see the full power of the world's best rate
+limiter.
+
+<Stepper>
+
+1. Add the rate-limiting Policy
+
+   Navigate to your route in the **Route Designer** (**Code** >
+   `routes.oas.json`), click the **Policies** dropdown, then click **Add
+   Policy** on the request pipeline.
+
+   <ModalScreenshot>
+
+   ![Add policy](../../public/media/step-2-add-rate-limiting/image.png)
+
+   </ModalScreenshot>
+
+   Search for the rate limiting policy (not the "Complex" one) and click it.
+
+   <ModalScreenshot>
+
+   ![Add rate-limiting policy](../../public/media/step-2-add-rate-limiting/choose-rate-limiter.png)
+
+   </ModalScreenshot>
+
+   By default, the policy will rate limit based on the caller's IP address (as
+   indicated by the `rateLimitBy` field). It will allow 2 requests
+   (`requestsAllowed`) every 1 minute (`timeWindowMinutes`). You can explore the
+   rest of the policy's documentation and configuration in the right panel.
+
+   ![Rate limiting policy](../../public/media/step-2-add-rate-limiting/create-policy.png)
+
+   To apply the policy, click **OK**. Then, save your changes to redeploy.
+
+1. Testing your Policy
+
+   Now try firing some requests against your API. You should receive a **429 Too
+   many requests** on your 3rd request.
+
+   <ModalScreenshot>
+
+   ![429 response](../../public/media/step-2-add-rate-limiting/test-api.png)
+
+   </ModalScreenshot>
+
+   Your rate limiting policy is now intercepting excess requests, protecting the
+   `getting-started` API.
+
+</Stepper>
+
+**NEXT** Try
+[Step 3 - Add API Key Authentication](./step-3-add-api-key-auth.mdx).