Zuplo API nutzen: Eine Anleitung

Wenn Sie über Zuplo gelesen haben und etwas Echtes damit veröffentlichen möchten, ist dies der richtige Beitrag für Sie. Die Plattform ist schnell zu erlernen, aber die Dokumentation ist über Portal-Workflows, CLI-Befehle und Artikel im Lernzentrum verteilt. Dieser Leitfaden fügt die Teile zu einem Tutorial zusammen: Erstellen Sie ein Projekt, machen Sie eine Route verfügbar, fügen Sie API-Schlüssel-Authentifizierung und Ratenbegrenzung hinzu, schreiben Sie eine benutzerdefinierte TypeScript-Richtlinie, stellen Sie sie am Edge bereit und testen Sie das Ganze mit Apidog.

App herunterladen

Am Ende haben Sie ein funktionierendes API-Gateway, das vor Ihrem Origin läuft, mit Authentifizierung, Ratenbegrenzung, einem automatisch generierten Entwicklerportal und einem CI-freundlichen Git-Workflow. Die gesamte Anleitung dauert etwa dreißig Minuten.

Wenn Sie noch unschlüssig sind, ob Zuplo das richtige Werkzeug ist, beginnen Sie mit unserem begleitenden Beitrag: Was ist das Zuplo API Gateway. Für alles Weitere behandelt die Zuplo-Dokumentation Randfälle, die dieser Leitfaden auslässt.

TL;DR

Registrieren Sie sich unter portal.zuplo.com oder erstellen Sie ein lokales Projekt mit npm create zuplo.
Definieren Sie Routen in config/routes.oas.json und leiten Sie diese mit dem URL Forward Handler an Ihren Ursprung weiter.
Fügen Sie eingehende Richtlinien (API-Schlüssel-Authentifizierung, Ratenbegrenzung, Schema-Validierung) hinzu, indem Sie die Routendatei bearbeiten oder durch den Route Designer klicken.
Schreiben Sie benutzerdefinierte Logik als TypeScript-Module in modules/; die Laufzeit bietet Ihnen typisierten Zugriff auf Anfrage, Kontext und Umgebung.
Pushen Sie in Ihren verknüpften Git-Branch, um eine Vorschauumgebung bereitzustellen; mergen Sie, um in über 300 Edge-Standorten live zu gehen.
Testen Sie jede Route mit Apidog, bevor Sie sie in die Produktion überführen.
Die kostenlose Stufe umfasst 100.000 Anfragen pro Monat; der Builder-Plan kostet 25 $ pro Monat.

Voraussetzungen

Bevor Sie beginnen, benötigen Sie drei Dinge:

Ein Zuplo-Konto
Eine Origin-API, vor die Sie das Gateway stellen können. Wenn Sie keine haben, verwenden Sie https://echo.zuplo.io, die alles widerspiegelt, was Sie ihr senden.
Node.js 18 oder höher, wenn Sie die CLI verwenden möchten.

Für die lokale Entwicklung benötigen Sie auch einen Code-Editor. VS Code mit der TypeScript-Erweiterung ist der Weg des geringsten Widerstands, und Sie können es mit der Apidog VS Code-Erweiterung koppeln, um Anfragen direkt aus Ihrem Editor zu senden.

Schritt 1: Ihr Zuplo-Projekt erstellen

Sie haben zwei Möglichkeiten, zu beginnen: über das Webportal oder die CLI. Die meisten Teams beginnen im Portal, da es schneller zu demonstrieren ist, und wechseln dann zur CLI, wenn sie CI/CD wünschen.

Option A: Portal-zuerst

Melden Sie sich unter portal.zuplo.com an.
Klicken Sie auf „Neues Projekt“ und wählen Sie einen Namen wie acme-gateway.
Wählen Sie „Leeres Projekt“, damit nichts automatisch erstellt wird.
Der Tab „Code“ öffnet sich mit einer Starter-Dateistruktur.

Das Portal verknüpft das Projekt standardmäßig mit einem verwalteten Git-Repository. Sie können Ihr eigenes GitHub-, GitLab-, Bitbucket- oder Azure DevOps-Repository später in den Einstellungen verbinden.

Option B: CLI-zuerst

Die CLI erstellt das gleiche Projektlayout lokal, sodass Sie in Ihrer IDE bearbeiten und Git von Anfang an verwenden können.

npm create zuplo@latest -- --name acme-gateway
cd acme-gateway
npm install
npm run dev

Der Dev-Server startet auf Port 9000 und zeigt einen Link zum lokalen Route Designer unter `http://localhost:9100` an. Jede Änderung, die Sie im Editor oder im Designer vornehmen, wird sofort neu geladen.

Um das lokale Projekt mit Ihrem Zuplo-Konto zu verknüpfen, sobald Sie zur Bereitstellung bereit sind:

npx zuplo link

Wählen Sie das Konto und die Umgebung, wenn Sie dazu aufgefordert werden. Von hier aus stellt `npx zuplo deploy` den aktuellen Git-Branch bereit.

Schritt 2: Ihre erste Route definieren

Öffnen Sie config/routes.oas.json. Dies ist ein OpenAPI 3-Dokument mit Zuplo-Erweiterungen für Handler und Richtlinien. Fügen Sie eine Route hinzu, die `GET /v1/products` an Ihren Ursprung weiterleitet:

{
  "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" }
        }
      }
    }
  }
}

Ein paar Details, die es wert sind, beachtet zu werden. Die `x-zuplo-route`-Erweiterung ist der Ort, an dem Zuplo in einer ansonsten Standard-OpenAPI-Datei existiert. Der `handler` beschreibt, was passiert, wenn die Route übereinstimmt; `urlForwardHandler` ist der integrierte Proxy. Die Referenz `${env.ORIGIN_URL}` greift auf Umgebungsvariablen zu, sodass Sie verschiedene Backends pro Umgebung ansprechen können.

Setzen Sie `ORIGIN_URL` über Einstellungen > Umgebungsvariablen im Portal oder indem Sie `config/.env` lokal bearbeiten. Verwenden Sie `https://echo.zuplo.io`, wenn Sie noch keinen echten Ursprung haben.

Speichern Sie, und der lokale Dev-Server lädt neu. Rufen Sie `http://localhost:9000/v1/products` auf, und Sie sollten die gespiegelte Anfrage sehen. Bereitgestellte Gateways antworten stattdessen vom nächstgelegenen Edge-Rechenzentrum.

Schritt 3: API-Schlüssel-Authentifizierung hinzufügen

Öffentliche APIs benötigen Anmeldeinformationen. Zuplo bietet einen verwalteten API-Schlüssel-Dienst, sodass Sie keinen eigenen Schlüsselspeicher aufbauen müssen.

Bearbeiten Sie die Route, um die eingehende Richtlinie hinzuzufügen:

"policies": {
  "inbound": ["api-key-auth"]
}

Fügen Sie dann die Richtliniendefinition zu `config/policies.json` hinzu (Zuplo erstellt diese Datei, wenn Sie zum ersten Mal eine Richtlinie hinzufügen):

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

Erstellen Sie nun einen Consumer (die Entität, die einen oder mehrere API-Schlüssel besitzt):

Gehen Sie im Portal zu Dienste > API-Schlüssel-Dienst.
Klicken Sie auf „Consumer erstellen“.
Setzen Sie das Subjekt auf eine stabile Kennung wie acme-customer-1.
Fügen Sie die E-Mail-Adresse der Person hinzu, die den Schlüssel verwalten soll.
Kopieren Sie den generierten API-Schlüssel.

Testen Sie mit Curl. Ohne den Header sollten Sie einen 401-Fehler sehen:

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

Mit dem Header sollten Sie die ursprüngliche 200-Antwort sehen:

curl -i https://YOUR-PROJECT.zuplo.app/v1/products \
  -H "Authorization: Bearer YOUR_API_KEY"
# HTTP/2 200

Wenn Sie dies lieber von einem echten Client aus steuern möchten, importieren Sie die OpenAPI-Spezifikation des Gateways in Apidog, setzen Sie einen globalen Header für `Authorization: Bearer {{api_key}}` und binden Sie `api_key` an eine Umgebungsvariable. So erhalten Sie in Sekundenschnelle eine saubere Testoberfläche für jede Route.

Schritt 4: Ratenbegrenzung für die Route

Veröffentlichen Sie niemals eine öffentliche API ohne Ratenbegrenzungen. Die Standard-Ratenbegrenzungsrichtlinie von Zuplo bietet Ihnen Drosselung pro IP, pro Schlüssel oder pro benutzerdefiniertem Attribut.

Fügen Sie es nach der Authentifizierung zur eingehenden Liste hinzu:

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

Definieren Sie es in `config/policies.json`:

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

`rateLimitBy: "sub"` ordnet den Bucket dem authentifizierten Subjekt aus der API-Schlüsselrichtlinie zu, sodass jeder Kunde sein eigenes Budget von 60 Anfragen pro Minute erhält. Ersetzen Sie dies durch "ip", wenn Sie anonymen Datenverkehr drosseln möchten.

Die 61. Anfrage innerhalb eines sechzig Sekunden Fensters gibt 429 mit angehängten Wiederholungs-Headern zurück. Testen Sie dies, indem Sie 70 Anfragen in einer Schleife abfeuern und beobachten, wie sich die Antwortcodes ändern.

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

Sie sollten 60 Zeilen mit `200` und 10 Zeilen mit `429` sehen.

Schritt 5: Anforderungs-Payloads validieren

Wenn Sie eine POST-Route haben, die einen JSON-Body empfängt, fängt die Anforderungsvalidierungsrichtlinie fehlerhafte Payloads am Gateway ab, anstatt an Ihrem Ursprung. Sie verwendet das in Ihre OpenAPI-Operation eingebettete JSON-Schema, sodass Sie dies kostenlos erhalten, wenn Ihre Spezifikation korrekt ist.

Fügen Sie eine Route mit einem Anforderungs-Body hinzu:

"/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": { /* same as above */ },
      "policies": {
        "inbound": [
          "api-key-auth",
          "rate-limit-by-key",
          "validate-request"
        ]
      }
    }
  }
}

Fügen Sie die Richtlinie hinzu:

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

Nun wird eine POST-Anfrage mit einem fehlenden Feld mit einem 400-Fehler abgelehnt, bevor sie Ihren Ursprung erreicht. Testen Sie dies mit Apidog, indem Sie eine „Happy Path“-Anfrage, eine Anfrage mit „fehlendem Pflichtfeld“ und eine Anfrage mit „falschem Enum-Wert“ als separate Beispiele in derselben Anfragesammlung speichern. Sie können alle drei mit einem Klick ausführen.

Schritt 6: Eine benutzerdefinierte TypeScript-Richtlinie schreiben

Vorgefertigte Richtlinien decken die meisten Bedürfnisse von Teams ab. Der Sinn von Zuplo ist jedoch der Moment, in dem Sie etwas Individuelles benötigen. Hier ist eine ausgehende Richtlinie, die einen `Cache-Control`-Header für bezahlte Kunden und `no-store` für kostenlose hinzufügt.

Erstellen Sie `modules/tiered-cache.ts`:

import { ZuploRequest, ZuploContext, HttpProblems } 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;
}

Binden Sie es in `config/policies.json` ein:

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

Und referenzieren Sie es von der Route aus:

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

Die benutzerdefinierte Richtlinie ist nur eine Funktion. Sie können sie mit Vitest oder Jest testen, indem Sie eine synthetische `Response` und `ZuploRequest` übergeben und die Header überprüfen, ohne dass ein Integrations-Harness erforderlich ist.

Schritt 7: Am Edge bereitstellen

Die Bereitstellung ist ein Git-Push.

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

Zuplo erstellt für jeden Branch eine Vorschauumgebung und gibt die URL im Build-Log aus. Die Vorschau erhält eine eigene Subdomain wie `https://acme-gateway-feature-products-gateway-abc123.zuplo.app`, wobei alle Ihre Richtlinien aktiv sind und auf die für diese Umgebung festgelegte `ORIGIN_URL` zeigen.

Testen Sie die Vorschau-URL mit Apidog, indem Sie sie als neue Umgebung in Ihrem Projekt festlegen. Führen Sie Ihre vollständige Testsuite dagegen aus. Wenn alles bestanden ist, mergen Sie den Branch.

git checkout main
git merge feature/products-gateway
git push origin main

Das Mergen löst die Produktionsbereitstellung aus. Innerhalb von sechzig Sekunden ist die neue Version in über 300 Edge-Standorten live. Das Promoten und Zurückrollen sind beides `git push`-Operationen; es gibt keine separate Benutzeroberfläche.

Schritt 8: Das Entwicklerportal generieren

Das Portal wird unter `https://YOUR-PROJECT.developers.zuplo.com` gehostet und bei jeder Bereitstellung neu erstellt. Es umfasst:

Eine Seite pro Route, mit Schema, Beschreibung und einer Testkonsole.
Codebeispiele in cURL, JavaScript, Python, Go und einigen anderen Sprachen.
Self-Service-API-Schlüssel-Ausgabe für jeden Besucher, der sich anmeldet.
Branding-Steuerungen im Portal unter Entwicklerportal > Einstellungen.

Wenn Ihre OpenAPI-Spezifikation gute Beschreibungen und Beispiele enthält, sieht das Portal ohne weitere Arbeit fertig aus. Wenn Ihre Spezifikation dünn ist, werden Sie es jetzt herausfinden.

Zur Anpassung wird die Portal-Quelle als separate Next.js-App geliefert, die Sie vom Zuplo Developer Portal Repo auf GitHub forken können. Die meisten Teams bleiben bei der gehosteten Version.

Schritt 9: Alles mit Apidog testen

Sobald Ihr Gateway live ist, ist die Disziplin, die Produktionszwischenfälle verhindert, das Testen jeder Route, jeder Richtlinie und jedes Fehlerpfads. Apidog macht dies schnell.

Der Workflow, der gut funktioniert:

Importieren Sie die OpenAPI-Spezifikation des Gateways von `https://YOUR-PROJECT.zuplo.app/openapi`. Apidog wandelt jede Operation in eine Anfrage um, die Sie ausführen können.
Erstellen Sie Umgebungen für `local`, `preview` und `production`, jede mit ihrer eigenen `base_url` und `api_key`.
Speichern Sie mindestens drei Anfragen pro Route: Happy Path, Authentifizierungsfehler und Ratenbegrenzungs-Trigger. Führen Sie diese als Gruppe vor jeder Bereitstellung aus.
Nutzen Sie die automatisierten Testszenarien von Apidog, um Aufrufe zu verketten (ein Produkt erstellen, auflisten, löschen) und Antwortformen zu überprüfen.
Generieren Sie Codebeispiele in der primären Sprache Ihres Teams und fügen Sie diese in Ihre Runbooks ein.

Wenn Sie von Postman migrieren, führt der Leitfaden zum API-Testen ohne Postman durch den Import. Laden Sie Apidog herunter, falls Sie dies noch nicht getan haben.

Häufige Fragen zur Verwendung von Zuplo

Wie wechsle ich eine Route zwischen Umgebungen, ohne die Spezifikation zu ändern?

Verwenden Sie Umgebungsvariablen. Definieren Sie `ORIGIN_URL` pro Umgebung in den Portal-Einstellungen oder lokal in `config/.env`, und referenzieren Sie es als `${env.ORIGIN_URL}` innerhalb der Handler-Optionen. Die Route bleibt identisch; nur die Variable ändert sich.

Kann ich Zuplo offline betreiben?

Ja. `npm run dev` startet ein lokales Gateway auf Port 9000 mit dem lokalen Route Designer auf Port 9100. Benutzerdefinierte Richtlinien, Validierung und Ratenbegrenzung funktionieren alle lokal; das Einzige, was eine Internetverbindung erfordert, ist der verwaltete API-Schlüssel-Dienst, und Sie können `npx zuplo link` ausführen, um den Cloud-Dienst von Ihrer lokalen Instanz aus zu nutzen.

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

Führen Sie `git revert` für den Merge-Commit aus und pushen Sie. Zuplo stellt den vorherigen Zustand erneut bereit. Es gibt keinen separaten „Rollback“-Button, da die Git-Historie die einzige Quelle der Wahrheit ist.

Was passiert mit laufenden Anfragen während einer Bereitstellung?

Bereitstellungen sind am Edge atomar; laufende Anfragen werden mit der alten Version abgeschlossen und neue Anfragen erreichen die neue Version. Es gibt kein Ausfallfenster.

Kann ich Zuplo mit gRPC oder WebSockets verwenden?

Ja. Der `urlForwardHandler` proxyt WebSocket-Upgrades transparent, und gRPC wird über den gRPC-Handler unterstützt. REST und GraphQL sind erstklassig und der häufigste Fall.

Wie mache ich meine Zuplo-API für KI-Agenten zugänglich?

Fügen Sie den MCP Server Handler einer Route hinzu, verweisen Sie ihn auf Ihre OpenAPI-Spezifikation und wählen Sie die Operationen aus, die offengelegt werden sollen. Dieselben Authentifizierungs- und Ratenbegrenzungsrichtlinien gelten für MCP-Anfragen. Die Zuplo MCP Server-Dokumentation beschreibt die Einrichtung.

Wie viel kostet das Gateway in der Produktion?

Die kostenlose Stufe umfasst 100.000 Anfragen pro Monat. Der Builder-Plan fügt 1 Million Anfragen für 25 $ pro Monat hinzu, und zusätzliche Anfragen kosten 100 $ pro 100.000. Die Enterprise-Preise beginnen bei 1.000 $ pro Monat bei einem Jahresvertrag. Eine vollständige Aufschlüsselung finden Sie auf der Zuplo-Preisgestaltungsseite.

Fazit

Sie haben nun ein funktionierendes Zuplo-Gateway mit API-Schlüssel-Authentifizierung, Ratenbegrenzung pro Schlüssel, Anforderungsvalidierung, einer benutzerdefinierten ausgehenden TypeScript-Richtlinie und einem Entwicklerportal, alles über Git zum globalen Edge bereitgestellt. Dasselbe Projekt verwaltet Vorschauumgebungen, Produktions-Rollouts und den Zugriff von KI-Agenten über MCP.

Das Element, das es stabil hält, ist die Testschleife. Verwenden Sie Apidog für jede Vorschau, bevor sie gemergt wird, und Sie werden fehlerhafte Authentifizierungs-Header, fehlende Schemafelder und Ratenbegrenzungen, die versehentlich zu großzügig waren, erkennen, bevor sie in Produktion gehen. Laden Sie Apidog herunter und binden Sie es noch heute in Ihr Gateway ein.

App herunterladen