Comment utiliser l'API Zuplo ?

Si vous avez lu des informations sur Zuplo et souhaitez réaliser quelque chose de concret avec, cet article est fait pour vous. La plateforme est rapide à prendre en main, mais la documentation est répartie entre les flux du portail, les commandes CLI et les articles du centre d'apprentissage. Ce guide rassemble toutes ces informations en un seul tutoriel : créer un projet, exposer une route, ajouter une authentification par clé API et une limitation de débit, écrire une politique TypeScript personnalisée, déployer en périphérie et tester l'ensemble avec Apidog.

bouton

À la fin, vous disposerez d'une passerelle API fonctionnelle placée devant votre origine, avec authentification, limitation de débit, un portail développeur auto-généré et un flux de travail Git compatible CI. L'ensemble du processus prend environ trente minutes.

Si vous hésitez encore à savoir si Zuplo est le bon outil, commencez par notre article complémentaire : Qu'est-ce que la passerelle API Zuplo. Pour tout le reste, la documentation Zuplo couvre les cas limites que ce guide ne mentionne pas.

En bref

Inscrivez-vous sur portal.zuplo.com ou créez un projet local avec npm create zuplo.
Définissez les routes dans config/routes.oas.json et transférez-les vers votre origine avec le gestionnaire URL Forward Handler.
Ajoutez des politiques entrantes (authentification par clé API, limitation de débit, validation de schéma) en modifiant le fichier de route ou en utilisant le Concepteur de Route.
Écrivez une logique personnalisée sous forme de modules TypeScript dans modules/ ; l'environnement d'exécution vous donne un accès typé aux requêtes, au contexte et à l'environnement.
Poussez vers votre branche Git liée pour déployer un environnement de prévisualisation ; fusionnez pour déployer en production sur plus de 300 emplacements périphériques.
Testez chaque route avec Apidog avant de la promouvoir en production.
La tarification commence gratuitement avec 100 000 requêtes par mois ; le plan Builder coûte 25 $ par mois.

Prérequis

Vous avez besoin de trois choses avant de commencer :

Un compte Zuplo
Une API d'origine devant laquelle placer la passerelle. Si vous n'en avez pas, utilisez https://echo.zuplo.io, qui renvoie en écho tout ce que vous lui envoyez.
Node.js 18 ou version supérieure si vous prévoyez d'utiliser la CLI.

Pour le développement local, vous avez également besoin d'un éditeur de code. VS Code avec l'extension TypeScript est la voie la moins résistante, et vous pouvez l'associer à l'extension Apidog VS Code pour envoyer des requêtes sans quitter votre éditeur.

Étape 1 : Créez votre projet Zuplo

Vous avez deux façons de commencer : le portail web ou la CLI. La plupart des équipes commencent par le portail car c'est plus rapide pour une démonstration, puis migrent vers la CLI lorsqu'elles souhaitent utiliser le CI/CD.

Option A : Portail d'abord

Connectez-vous sur portal.zuplo.com.
Cliquez sur « Nouveau Projet » et choisissez un nom comme acme-gateway.
Choisissez « Projet vide » pour que rien ne soit créé automatiquement.
L'onglet Code s'ouvre sur une arborescence de fichiers de démarrage.

Le portail lie le projet à un dépôt Git géré par défaut. Vous pouvez connecter votre propre dépôt GitHub, GitLab, Bitbucket ou Azure DevOps depuis les Paramètres ultérieurement.

Option B : CLI d'abord

La CLI génère la même structure de projet localement afin que vous puissiez éditer dans votre IDE et utiliser Git dès le premier jour.

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

Le serveur de développement démarre sur le port 9000 et affiche un lien vers le Concepteur de Route local à l'adresse http://localhost:9100. Toute modification que vous apportez dans l'éditeur ou dans le concepteur est rechargée à chaud immédiatement.

Pour lier le projet local à votre compte Zuplo une fois que vous êtes prêt à déployer :

npx zuplo link

Choisissez le compte et l'environnement lorsque vous y êtes invité. À partir de là, npx zuplo deploy déploie la branche Git actuelle.

Étape 2 : Définissez votre première route

Ouvrez config/routes.oas.json. Il s'agit d'un document OpenAPI 3 avec des extensions Zuplo pour les gestionnaires et les politiques. Ajoutez une route qui transfère GET /v1/products à votre origine :

{
  "openapi": "3.1.0",
  "info": { "title": "Passerelle Acme", "version": "1.0.0" },
  "paths": {
    "/v1/products": {
      "get": {
        "summary": "Lister les produits",
        "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": "Succès" }
        }
      }
    }
  }
}

Quelques détails à noter. L'extension x-zuplo-route est l'endroit où Zuplo réside dans un fichier OpenAPI par ailleurs standard. Le handler décrit ce qui se passe lorsque la route correspond ; urlForwardHandler est le proxy intégré. La référence ${env.ORIGIN_URL} extrait les variables d'environnement afin que vous puissiez cibler différents backends par environnement.

Définissez ORIGIN_URL depuis Paramètres > Variables d'environnement dans le portail, ou en modifiant config/.env localement. Utilisez https://echo.zuplo.io si vous n'avez pas encore d'origine réelle.

Enregistrez et le serveur de développement local se recharge. Accédez à http://localhost:9000/v1/products et vous devriez voir la requête en écho. Les passerelles déployées répondront depuis le centre de données périphérique le plus proche.

Étape 3 : Ajoutez l'authentification par clé API

Les API publiques ont besoin d'identifiants. Zuplo fournit un service de clés API géré afin que vous n'ayez pas à construire votre propre magasin de clés.

Modifiez la route pour ajouter la politique entrante :

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

Ajoutez ensuite la définition de la politique à config/policies.json (Zuplo crée ce fichier la première fois que vous ajoutez une politique) :

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

Créez maintenant un consommateur (l'entité qui possède une ou plusieurs clés API) :

Allez dans Services > Service de clés API dans le portail.
Cliquez sur « Créer un consommateur ».
Définissez le sujet sur un identifiant stable comme acme-customer-1.
Ajoutez l'e-mail de la personne qui devrait gérer la clé.
Copiez la clé API générée.

Testez avec curl. Sans l'en-tête, vous devriez voir un 401 :

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

Avec l'en-tête, vous devriez voir la réponse originale 200 :

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

Si vous préférez piloter cela depuis un client réel, importez la spécification OpenAPI de la passerelle dans Apidog, définissez un en-tête global pour Authorization: Bearer {{api_key}}, et liez api_key à une variable d'environnement. Vous obtenez une surface de test claire pour chaque route en quelques secondes.

Étape 4 : Limitez le débit de la route

Ne déployez jamais une API publique sans limites de débit. La politique de limitation de débit par défaut de Zuplo vous offre une régulation par IP, par clé ou par attribut personnalisé.

Ajoutez-la à la liste entrante, après l'authentification :

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

Définissez-la dans 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" attribue le seau au sujet authentifié de la politique de clé API, de sorte que chaque client dispose de son propre budget de 60 requêtes par minute. Remplacez par "ip" si vous souhaitez réguler le trafic anonyme.

La 61e requête dans une fenêtre de soixante secondes renvoie un 429 avec des en-têtes de nouvelle tentative. Testez-le en envoyant 70 requêtes en boucle et en observant les codes de réponse changer.

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

Vous devriez voir 60 lignes indiquant 200 et 10 lignes indiquant 429.

Étape 5 : Validez les charges utiles des requêtes

Si vous avez une route POST qui accepte un corps JSON, la politique de validation des requêtes intercepte les charges utiles malformées au niveau de la passerelle au lieu de votre origine. Elle utilise le schéma JSON intégré dans votre opération OpenAPI, vous bénéficiez donc de cette fonctionnalité gratuitement si votre spécification est précise.

Ajoutez une route avec un corps de requête :

"/v1/products": {
  "post": {
    "summary": "Créer un produit",
    "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"
        ]
      }
    }
  }
}

Ajoutez la politique :

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

Maintenant, une requête POST avec un champ manquant est rejetée avec un 400 avant d'atteindre votre origine. Testez-la avec Apidog en enregistrant une requête « chemin heureux », une requête « champ obligatoire manquant » et une requête « valeur d'énumération incorrecte » comme exemples distincts dans le même groupe de requêtes. Vous pouvez exécuter les trois en un seul clic.

Étape 6 : Écrivez une politique TypeScript personnalisée

Les politiques pré-construites couvrent la plupart des besoins des équipes. L'intérêt de Zuplo, cependant, est le moment où vous avez besoin de quelque chose de personnalisé. Voici une politique sortante qui ajoute un en-tête Cache-Control pour les clients payants et no-store pour les clients gratuits.

Créez 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;
}

Connectez-la dans config/policies.json :

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

Et référencez-la depuis la route :

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

La politique personnalisée est juste une fonction. Vous pouvez la tester unitairement avec Vitest ou Jest en lui passant un Response et un ZuploRequest synthétiques et en vérifiant les en-têtes, aucun harnais d'intégration n'est requis.

Étape 7 : Déployez en périphérie

Le déploiement est un push Git.

git add .
git commit -m "Ajoute la passerelle de produits avec authentification, limitation de débit et cache à plusieurs niveaux"
git push origin feature/products-gateway

Zuplo construit un environnement de prévisualisation pour chaque branche et affiche l'URL dans le journal de build. L'aperçu obtient son propre sous-domaine comme https://acme-gateway-feature-products-gateway-abc123.zuplo.app, avec toutes vos politiques actives et pointant vers la valeur de ORIGIN_URL définie pour cet environnement.

Testez l'URL de prévisualisation avec Apidog en la définissant comme un nouvel environnement dans votre projet. Exécutez votre suite de tests complète contre elle. Si tout passe, fusionnez la branche.

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

La fusion déclenche le déploiement en production. En soixante secondes, la nouvelle version est en ligne dans plus de 300 emplacements périphériques. La promotion et la restauration sont toutes deux des opérations git push ; il n'y a pas d'interface utilisateur distincte.

Étape 8 : Générez le portail développeur

Le portail est hébergé à l'adresse https://YOUR-PROJECT.developers.zuplo.com et est reconstruit à chaque déploiement. Il comprend :

Une page par route, avec le schéma, la description et une console d'essai.
Des exemples de code en cURL, JavaScript, Python, Go, et quelques autres.
Délivrance de clés API en libre-service pour tout visiteur qui s'inscrit.
Contrôles de branding dans le portail sous Portail développeur > Paramètres.

Si votre spécification OpenAPI contient de bonnes descriptions et exemples, le portail semble terminé sans travail supplémentaire. Si votre spécification est mince, c'est le moment de le découvrir.

Pour personnaliser, la source du portail est fournie en tant qu'application Next.js distincte que vous pouvez forker depuis le dépôt GitHub du portail développeur Zuplo. La plupart des équipes restent sur la version hébergée.

Étape 9 : Testez tout avec Apidog

Une fois votre passerelle en ligne, la discipline qui prévient les incidents de production est de tester chaque route, chaque politique et chaque chemin d'erreur. Apidog rend cela rapide.

Le flux de travail qui fonctionne bien :

Importez la spécification OpenAPI de la passerelle depuis https://YOUR-PROJECT.zuplo.app/openapi. Apidog transforme chaque opération en une requête que vous pouvez exécuter.
Créez des environnements pour local, preview et production, chacun avec son propre base_url et api_key.
Enregistrez au minimum trois requêtes par route : chemin heureux, échec d'authentification et déclencheur de limite de débit. Exécutez-les en groupe avant chaque déploiement.
Utilisez les scénarios de test automatisés d'Apidog pour enchaîner les appels (créer un produit, le lister, le supprimer) et vérifier les formats de réponse.
Générez des exemples de code dans la langue principale de votre équipe et collez-les dans vos runbooks.

Si vous migrez de Postman, le guide de test d'API sans Postman explique l'importation. Téléchargez Apidog si ce n'est pas déjà fait.

Questions fréquentes sur l'utilisation de Zuplo

Comment basculer une route entre les environnements sans modifier la spécification ?

Utilisez les variables d'environnement. Définissez ORIGIN_URL par environnement dans les Paramètres du portail ou dans config/.env localement, et référencez-la comme ${env.ORIGIN_URL} dans les options du gestionnaire. La route reste identique ; seule la variable change.

Puis-je exécuter Zuplo hors ligne ?

Oui. npm run dev démarre une passerelle locale sur le port 9000 avec le Concepteur de Route local sur 9100. Les politiques personnalisées, la validation et la limitation de débit fonctionnent toutes localement ; la seule chose qui nécessite une connexion internet est le service de clé API géré, et vous pouvez exécuter npx zuplo link pour utiliser le service cloud depuis votre instance locale.

Comment annuler un mauvais déploiement ?

Faites un git revert du commit de fusion et poussez. Zuplo redéploie l'état précédent. Il n'y a pas de bouton « annuler » séparé car l'historique Git est la source de vérité.

Que se passe-t-il pour les requêtes en cours de traitement pendant un déploiement ?

Les déploiements sont atomiques en périphérie ; les requêtes en cours de traitement se terminent sur l'ancienne version et les nouvelles requêtes atteignent la nouvelle version. Il n'y a pas de fenêtre d'indisponibilité.

Puis-je utiliser Zuplo avec gRPC ou WebSockets ?

Oui. Le urlForwardHandler proxy les mises à niveau WebSocket de manière transparente, et gRPC est pris en charge via le gestionnaire gRPC. REST et GraphQL sont des cas de premier ordre et les plus courants.

Comment exposer mon API Zuplo aux agents IA ?

Ajoutez le gestionnaire de serveur MCP à une route, pointez-le vers votre spécification OpenAPI et choisissez les opérations à exposer. Les mêmes politiques d'authentification et de limitation de débit s'appliquent aux requêtes MCP. La documentation du serveur MCP Zuplo couvre la configuration.

Combien coûte la passerelle en production ?

Le niveau gratuit couvre 100 000 requêtes par mois. Le plan Builder ajoute 1 million de requêtes pour 25 $ par mois, et les requêtes supplémentaires coûtent 100 $ pour 100 000. La tarification Enterprise commence à 1 000 $ par mois avec un contrat annuel. Détails complets sur la page de tarification Zuplo.

Conclusion

Vous disposez maintenant d'une passerelle Zuplo fonctionnelle avec authentification par clé API, limitation de débit par clé, validation des requêtes, une politique sortante TypeScript personnalisée et un portail développeur, le tout étant déployé via Git en périphérie mondiale. Le même projet gère les environnements de prévisualisation, les déploiements en production et l'accès des agents IA via MCP.

L'élément qui assure sa stabilité est la boucle de test. Utilisez Apidog pour chaque prévisualisation avant la fusion, et vous détecterez les en-têtes d'authentification cassés, les champs de schéma manquants et les limites de débit accidentellement trop généreuses avant qu'ils ne soient déployés. Téléchargez Apidog et intégrez-le à votre passerelle dès aujourd'hui.

bouton