DEV Community

Cover image for Zuplo API nutzen: Eine Anleitung
Emre Demir
Emre Demir

Posted on • Originally published at apidog.com

Zuplo API nutzen: Eine Anleitung

Wenn Sie über Zuplo gelesen haben und direkt loslegen möchten, zeigt Ihnen dieser Leitfaden Schritt für Schritt, wie Sie ein voll funktionsfähiges API-Gateway aufsetzen. Er führt Sie durch das Erstellen eines Projekts, das Definieren von Routen, das Hinzufügen von API-Schlüssel-Authentifizierung und Ratenbegrenzung, das Schreiben einer eigenen TypeScript-Richtlinie, die Edge-Bereitstellung und das Testen mit Apidog.

Testen Sie Apidog noch heute

Am Ende steht ein API-Gateway vor Ihrem Origin, inklusive Authentifizierung, Ratenbegrenzung, Entwicklerportal und CI-freundlichem Git-Workflow – alles in etwa 30 Minuten umgesetzt.

Falls Sie unsicher sind, ob Zuplo das richtige Tool ist, lesen Sie zuerst: Was ist das Zuplo API Gateway. Für weitere Details und Spezialfälle empfiehlt sich die Zuplo-Dokumentation.

TL;DR

  • Registrieren bei portal.zuplo.com oder per CLI: npm create zuplo
  • Routen in config/routes.oas.json definieren, Weiterleitung via URL Forward Handler einrichten
  • Authentifizierung, Ratenbegrenzung, Schema-Validierung als Richtlinien hinzufügen
  • Eigene Logik als TypeScript-Module unter modules/ schreiben
  • Git-Branch pushen für Vorschau; Mergen bringt Deploy auf 300+ Edge-Standorte
  • Jede Route mit Apidog testen
  • Free Tier: 100.000 Anfragen/Monat, Builder-Plan: $25/Monat

Voraussetzungen

Bevor Sie starten, benötigen Sie:

  • Ein Zuplo-Konto
  • Eine Origin-API (z.B. https://echo.zuplo.io, falls keine eigene vorhanden)
  • Node.js 18+ (bei Nutzung der CLI)
  • Für lokale Entwicklung: einen Code-Editor (VS Code mit TypeScript-Erweiterung empfohlen). Koppeln Sie diesen mit der Apidog VS Code-Erweiterung für API-Tests direkt im Editor.

Schritt 1: Zuplo-Projekt erstellen

Sie starten entweder über das Webportal oder die CLI.

Option A: Portal

  1. Unter portal.zuplo.com anmelden
  2. „Neues Projekt“ auswählen, z.B. acme-gateway
  3. „Leeres Projekt“ wählen
  4. Tab „Code“ öffnet die Start-Dateistruktur

Das Portal verbindet das Projekt mit einem Git-Repository. Eigene Repos können später verknüpft werden (GitHub, GitLab, Bitbucket, Azure DevOps).

Option B: CLI

CLI legt das Projekt lokal an:

npm create zuplo@latest -- --name acme-gateway
cd acme-gateway
npm install
npm run dev
Enter fullscreen mode Exit fullscreen mode

Dev-Server läuft auf Port 9000, Route Designer unter http://localhost:9100. Änderungen werden sofort geladen.

Verknüpfen Sie das lokale Projekt mit Zuplo, wenn die Bereitstellung ansteht:

npx zuplo link
Enter fullscreen mode Exit fullscreen mode

Konto und Umgebung wählen, dann mit

npx zuplo deploy
Enter fullscreen mode Exit fullscreen mode

den aktuellen Git-Branch deployen.

Schritt 2: Erste Route definieren

Öffnen Sie config/routes.oas.json (OpenAPI 3 mit Zuplo-Erweiterungen) und fügen Sie z.B. folgende Route hinzu:

{
  "openapi": "3.1.0",
  "info": { "title": "Acme Gateway", "version": "1.0.0" },
  "paths": {
    "/v1/products": {
      "get": {
        "summary": "List products",
        "operationId": "list-products",
        "x-zuplo-route": {
          "corsPolicy": "anything-goes",
          "handler": {
            "export": "urlForwardHandler",
            "module": "$import(@zuplo/runtime)",
            "options": {
              "baseUrl": "${env.ORIGIN_URL}"
            }
          },
          "policies": { "inbound": [] }
        },
        "responses": {
          "200": { "description": "Success" }
        }
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Setzen Sie ORIGIN_URL in den Umgebungsvariablen des Portals oder lokal in config/.env. Testen Sie über http://localhost:9000/v1/products.

Schritt 3: API-Schlüssel-Authentifizierung

Fügen Sie in der Route unter policies.inbound "api-key-auth" hinzu:

"policies": {
  "inbound": ["api-key-auth"]
}
Enter fullscreen mode Exit fullscreen mode

Definieren Sie die Richtlinie in config/policies.json:

{
  "name": "api-key-auth",
  "policyType": "api-key-inbound",
  "handler": {
    "export": "ApiKeyInboundPolicy",
    "module": "$import(@zuplo/runtime)",
    "options": {
      "allowUnauthenticatedRequests": false
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Erstellen Sie einen Consumer im Portal unter Dienste > API-Schlüssel-Dienst. Kopieren Sie den API-Schlüssel.

Testen Sie mit Curl:

# Ohne Auth:
curl -i https://YOUR-PROJECT.zuplo.app/v1/products
# HTTP/2 401

# Mit Auth:
curl -i https://YOUR-PROJECT.zuplo.app/v1/products \
  -H "Authorization: Bearer YOUR_API_KEY"
# HTTP/2 200
Enter fullscreen mode Exit fullscreen mode

Für komfortable Tests: OpenAPI-Spec in Apidog importieren, Header global setzen, Schlüssel als Variable.

Schritt 4: Ratenbegrenzung einrichten

Fügen Sie "rate-limit-by-key" nach der Authentifizierung hinzu:

"policies": {
  "inbound": ["api-key-auth", "rate-limit-by-key"]
}
Enter fullscreen mode Exit fullscreen mode

Definieren Sie die Richtlinie:

{
  "name": "rate-limit-by-key",
  "policyType": "rate-limit-inbound",
  "handler": {
    "export": "RateLimitInboundPolicy",
    "module": "$import(@zuplo/runtime)",
    "options": {
      "rateLimitBy": "sub",
      "requestsAllowed": 60,
      "timeWindowMinutes": 1
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Testen Sie mit einer Schleife (60x 200, Rest 429):

for i in {1..70}; do
  curl -s -o /dev/null -w "%{http_code}\n" \
    https://YOUR-PROJECT.zuplo.app/v1/products \
    -H "Authorization: Bearer YOUR_API_KEY"
done | sort | uniq -c
Enter fullscreen mode Exit fullscreen mode

Schritt 5: Anforderungs-Payloads validieren

Für POST-Routen kann die Validierung automatisch erfolgen. Beispiel für OpenAPI:

"/v1/products": {
  "post": {
    "summary": "Create product",
    "operationId": "create-product",
    "requestBody": {
      "required": true,
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": ["name", "priceCents"],
            "properties": {
              "name": { "type": "string", "minLength": 1 },
              "priceCents": { "type": "integer", "minimum": 1 },
              "category": { "type": "string", "enum": ["food", "drink"] }
            }
          }
        }
      }
    },
    "x-zuplo-route": {
      "handler": { /* wie oben */ },
      "policies": {
        "inbound": [
          "api-key-auth",
          "rate-limit-by-key",
          "validate-request"
        ]
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Richtlinie in config/policies.json:

{
  "name": "validate-request",
  "policyType": "open-api-request-validation-inbound",
  "handler": {
    "export": "OpenApiRequestValidationInboundPolicy",
    "module": "$import(@zuplo/runtime)",
    "options": {
      "validateBody": "reject"
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Testen Sie verschiedene Fälle mit Apidog.

Schritt 6: Eigene TypeScript-Richtlinie

Für individuelle Logik Modul anlegen, z.B. modules/tiered-cache.ts:

import { ZuploRequest, ZuploContext } from "@zuplo/runtime";

interface PolicyOptions {
  paidPlanHeader: string;
  paidMaxAge: number;
}

export default async function (
  response: Response,
  request: ZuploRequest,
  context: ZuploContext,
  options: PolicyOptions,
): Promise<Response> {
  const plan = request.user?.data?.plan ?? "free";

  if (plan === "free") {
    response.headers.set("Cache-Control", "no-store");
  } else {
    response.headers.set(
      "Cache-Control",
      `public, max-age=${options.paidMaxAge}`,
    );
  }

  context.log.info(`Cache header set for plan=${plan}`);
  return response;
}
Enter fullscreen mode Exit fullscreen mode

In config/policies.json einbinden:

{
  "name": "tiered-cache",
  "policyType": "custom-code-outbound",
  "handler": {
    "export": "default",
    "module": "$import(./modules/tiered-cache)",
    "options": {
      "paidPlanHeader": "x-plan",
      "paidMaxAge": 300
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Route referenziert die Richtlinie:

"policies": {
  "inbound": ["api-key-auth", "rate-limit-by-key"],
  "outbound": ["tiered-cache"]
}
Enter fullscreen mode Exit fullscreen mode

Testbar mit Vitest/Jest direkt im Code.

Schritt 7: Edge-Bereitstellung

Deploy erfolgt per Git:

git add .
git commit -m "Add products gateway with auth, rate limit, and tiered cache"
git push origin feature/products-gateway
Enter fullscreen mode Exit fullscreen mode

Zuplo erstellt für jeden Branch eine Vorschau-URL, z.B. https://acme-gateway-feature-products-gateway-abc123.zuplo.app.

Mit Apidog als neue Umgebung testen. Nach Bestehen mergen:

git checkout main
git merge feature/products-gateway
git push origin main
Enter fullscreen mode Exit fullscreen mode

Produktiv innerhalb von 60 Sekunden auf 300+ Standorten live.

Schritt 8: Entwicklerportal generieren

Das Portal unter https://YOUR-PROJECT.developers.zuplo.com umfasst:

  • Dokumentation je Route mit Testkonsole
  • Codebeispiele (cURL, JS, Python, Go etc.)
  • Self-Service API-Key-Ausgabe
  • Branding-Steuerung

Eigene Anpassung via Fork aus dem Developer Portal Repo auf GitHub möglich.

Schritt 9: Alles mit Apidog testen

Testen Sie jede Route, Richtlinie und Fehlerpfad mit Apidog.

Empfohlener Workflow:

  1. OpenAPI-Spec von https://YOUR-PROJECT.zuplo.app/openapi in Apidog importieren
  2. Umgebungen für local, preview, production anlegen
  3. Mind. drei Anfragen pro Route speichern: Happy Path, Auth-Fehler, Ratenlimit-Trigger
  4. Automatisierte Testszenarien für Gesamtabläufe nutzen
  5. Codebeispiele generieren und in Runbooks aufnehmen

Migration von Postman? Siehe API-Testing ohne Postman.

Häufige Fragen zu Zuplo

Wie wechsle ich eine Route zwischen Umgebungen?

Über Umgebungsvariablen: ORIGIN_URL in den Einstellungen pro Umgebung setzen und als ${env.ORIGIN_URL} referenzieren.

Kann ich Zuplo offline nutzen?

Ja. npm run dev startet das lokale Gateway. Lediglich der API-Key-Service benötigt Internet.

Wie mache ich eine fehlerhafte Bereitstellung rückgängig?

git revert auf den Merge-Commit und pushen. Rollback erfolgt automatisch.

Was passiert mit laufenden Anfragen beim Deploy?

Edge-Bereitstellungen sind atomar: Alte Anfragen laufen aus, neue gehen auf die neue Version.

gRPC oder WebSockets möglich?

Ja. WebSockets werden durchgereicht, gRPC via Handler unterstützt.

KI-Agenten-Zugriff auf Zuplo-API?

MCP Server Handler auf Route legen, OpenAPI referenzieren, Operationen auswählen. Siehe Zuplo MCP Server Dokumentation.

Kosten in Produktion?

Free Tier: 100.000 Anfragen/Monat. Builder: 1 Mio. Anfragen für $25/Monat, weitere $100 pro 100.000. Enterprise ab $1.000/Jahr. Details auf der Preis-Seite.

Fazit

Sie haben jetzt ein Zuplo-Gateway mit API-Key-Auth, Ratenbegrenzung, Schema-Validierung, eigener Richtlinie und Entwicklerportal – alles via Git und Edge-Deploy. Auch Vorschau- und Produktionsumgebungen sind abgedeckt.

Der entscheidende Faktor: Testschleife! Nutzen Sie Apidog für jeden Preview-Branch, um Auth-Fehler, fehlende Felder und zu großzügige Limits rechtzeitig zu entdecken. Laden Sie Apidog herunter und integrieren Sie es in Ihr Gateway.

Top comments (0)