DEV Community

Cover image for Comment utiliser l'API Zuplo ?
Antoine Laurent
Antoine Laurent

Posted on • Originally published at apidog.com

Comment utiliser l'API Zuplo ?

Si vous avez lu des informations sur Zuplo et souhaitez passer à la pratique, ce guide est pour vous. La plateforme Zuplo est rapide à prendre en main, mais sa documentation est éparpillée entre le portail, la CLI et le centre d'apprentissage. Ce tutoriel rassemble tout pour vous permettre de créer un projet, exposer une route, ajouter une authentification par clé API, limiter le débit, écrire une politique TypeScript personnalisée, déployer en périphérie et tout tester avec Apidog.

Essayez Apidog dès aujourd'hui

À la fin, vous disposerez d'une passerelle API opérationnelle devant votre backend, avec authentification, limitation de débit, portail développeur auto-généré et workflow Git compatible CI. Comptez environ trente minutes pour tout mettre en place.

Si vous hésitez sur le choix de Zuplo, commencez par notre article complémentaire : Qu'est-ce que la passerelle API Zuplo. Pour les cas particuliers non couverts ici, la documentation Zuplo est complète.

En bref

  • Inscrivez-vous sur portal.zuplo.com ou créez un projet local avec npm create zuplo.
  • Définissez vos routes dans config/routes.oas.json et proxifiez-les vers votre backend avec le handler URL Forward.
  • Ajoutez des politiques entrantes (authentification par clé API, limitation de débit, validation de schéma) dans le fichier de route ou via le Route Designer.
  • Écrivez des politiques personnalisées en TypeScript dans modules/ avec accès typé aux requêtes et au contexte.
  • Déployez via Git : chaque branche génère un environnement de prévisualisation ; fusionnez pour passer en production sur plus de 300 edge locations.
  • Testez chaque route avec Apidog avant la promotion en prod.
  • Tarification : gratuit jusqu’à 100 000 requêtes/mois, plan Builder à 25 $/mois.

Prérequis

Avant de commencer, préparez :

  • Un compte Zuplo.
  • Une API d’origine à protéger. Si vous n’en avez pas, utilisez https://echo.zuplo.io (retourne tout ce que vous lui envoyez).
  • Node.js 18+ pour la CLI.

Pour le développement local, utilisez un éditeur comme VS Code (avec l’extension TypeScript). Associez-le à l’extension Apidog VS Code pour envoyer des requêtes directement depuis l’éditeur.

Étape 1 : Créez votre projet Zuplo

Option A : Portail

  1. Connectez-vous sur portal.zuplo.com.
  2. Cliquez sur « Nouveau Projet » et nommez-le (ex : acme-gateway).
  3. Choisissez « Projet vide ».
  4. L’onglet Code présente l’arborescence de départ.

Capture d'écran du portail Zuplo

Le projet est lié par défaut à un dépôt Git géré, mais vous pouvez connecter votre propre dépôt GitHub, GitLab, Bitbucket ou Azure DevOps dans les paramètres.

Option B : CLI

Générez la structure localement et commencez immédiatement en mode git.

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

Le serveur local écoute sur le port 9000 et le Route Designer local sur http://localhost:9100. Les modifications sont rechargées à chaud.

Pour lier votre projet local à Zuplo :

npx zuplo link
Enter fullscreen mode Exit fullscreen mode

Sélectionnez le compte et l’environnement. Ensuite, npx zuplo deploy déploie la branche git courante.

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

Ouvrez config/routes.oas.json (OpenAPI 3 avec extensions Zuplo). Exemple pour transférer GET /v1/products vers votre backend :

{
  "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" }
        }
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

L’extension x-zuplo-route configure le handler (ici urlForwardHandler) et les politiques. La variable ${env.ORIGIN_URL} permet de cibler différents backends selon l’environnement.

Définissez ORIGIN_URL dans les paramètres du portail ou dans config/.env localement. Utilisez https://echo.zuplo.io pour commencer.

Testez sur http://localhost:9000/v1/products : vous recevez un echo du backend.

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

Activez la politique dans votre route :

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

Ajoutez la définition dans 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

Créez un consommateur via Services > Service de clés API :

  1. Cliquez sur « Créer un consommateur ».
  2. Définissez un identifiant (ex : acme-customer-1).
  3. Ajoutez l’e-mail du gestionnaire.
  4. Copiez la clé API générée.

Testez :

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

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

Pour des tests plus avancés, importez la spec OpenAPI dans Apidog, ajoutez un header global Authorization: Bearer {{api_key}} et reliez api_key à une variable d’environnement.

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

Ajoutez la limitation de débit après l’authentification :

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

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
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

rateLimitBy: "sub" applique la limite par client authentifié (60 requêtes/min). Pour une régulation par IP, utilisez "ip".

Testez :

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

Vous verrez 60 réponses 200 et 10 réponses 429.

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

Pour un endpoint POST, la validation est automatique si le schéma OpenAPI est renseigné.

Exemple de route avec schéma :

"/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": { /* même handler qu'au-dessus */ },
      "policies": {
        "inbound": [
          "api-key-auth",
          "rate-limit-by-key",
          "validate-request"
        ]
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Définissez la politique :

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

Un POST mal formé reçoit un 400 avant même d’atteindre votre backend.

Testez différents scénarios dans Apidog : succès, champ obligatoire manquant, valeur d’énum incorrecte.

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

Pour aller au-delà du prêt-à-l’emploi, ajoutez vos propres politiques.

Exemple : ajouter un header Cache-Control différent selon le plan client.

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;
}
Enter fullscreen mode Exit fullscreen mode

Ajoutez-la à config/policies.json :

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

Référencez-la dans la route :

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

Testez votre politique comme une fonction unitaire avec Vitest ou Jest : passez-lui un objet Response synthétique et vérifiez les headers.

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

Déployez via git :

git add .
git commit -m "Ajoute la passerelle de produits avec authent, rate limiting et cache"
git push origin feature/products-gateway
Enter fullscreen mode Exit fullscreen mode

Chaque branche crée un environnement de prévisualisation avec URL dédiée (par ex. : https://acme-gateway-feature-products-gateway-abc123.zuplo.app), incluant toutes vos politiques.

Testez l’URL de preview dans Apidog en l’ajoutant comme environnement. Vérifiez toute votre suite de tests, puis fusionnez :

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

La production est déployée automatiquement en ~60 secondes, sans downtime.

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

Le portail développeur est accessible à https://YOUR-PROJECT.developers.zuplo.com, reconstruit à chaque déploiement :

  • Une page par route, avec schémas et console d’essai.
  • Exemples de code (cURL, JS, Python, Go…).
  • Self-service API key pour tout visiteur inscrit.
  • Branding personnalisable dans le portail.

Si votre spec OpenAPI est bien documentée, le portail est prêt sans effort supplémentaire.

Pour personnaliser davantage, forkez la source Next.js sur le dépôt GitHub du portail développeur Zuplo.

Étape 9 : Testez tout avec Apidog

Après déploiement, testez chaque route, politique et cas d’erreur. Apidog rend ce process rapide.

Capture d'écran de l'interface Apidog

Workflow recommandé :

  1. Importez la spec OpenAPI via https://YOUR-PROJECT.zuplo.app/openapi dans Apidog.
  2. Créez des environnements (local, preview, prod) avec leur propre base_url et api_key.
  3. Enregistrez trois requêtes/test par route : succès, échec authent, dépassement de limite.
  4. Utilisez les tests automatisés pour enchaîner des appels (création, liste, suppression de produit) et vérifier les réponses.
  5. Générez des snippets code pour vos runbooks.

Pour migrer depuis Postman, suivez le guide API testing without Postman. 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 spec ?

Utilisez des variables d’environnement : définissez ORIGIN_URL par environnement et référencez-la dans vos handlers. Modifiez la variable, pas la route.

Puis-je exécuter Zuplo hors ligne ?

Oui. npm run dev démarre la passerelle locale (port 9000) et le Route Designer (9100). Toutes les politiques fonctionnent localement, sauf le service de clé API géré (utilisez npx zuplo link pour le cloud).

Comment annuler un mauvais déploiement ?

Un simple git revert du commit fautif suivi d’un push suffit : Zuplo redéploie la version précédente (pas de bouton « annuler », git fait foi).

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

Déploiements atomiques : les requêtes en cours terminent sur l’ancienne version ; les nouvelles passent sur la nouvelle. Zéro downtime.

Puis-je utiliser Zuplo avec gRPC ou WebSockets ?

Oui. urlForwardHandler proxy les upgrades WebSocket, et gRPC est pris en charge. REST/GraphQL restent les cas les plus courants.

Comment exposer mon API Zuplo aux agents IA ?

Ajoutez le handler MCP Server à une route, pointez-le vers votre spec OpenAPI et sélectionnez les opérations à exposer. Les politiques existantes s’appliquent. Voir la doc MCP Server Zuplo.

Combien coûte la passerelle en production ?

Gratuit jusqu’à 100 000 requêtes/mois. Plan Builder : 1 million de requêtes pour 25 $/mois (+100 $ par 100 000 requêtes sup). Offre Enterprise à partir de 1 000 $/mois/an. Détails sur la tarification.

Conclusion

Vous avez maintenant une passerelle Zuplo complète : authentification par clé API, limitation de débit, validation des requêtes, politique TypeScript personnalisée et portail développeur, le tout déployé via Git sur le edge mondial. Prévisualisation, production et accès IA via MCP inclus dans le même repo.

Pour fiabiliser, testez chaque preview avec Apidog avant fusion : vous repérerez les en-têtes d’auth cassés, les schémas incomplets ou les quotas trop larges avant qu’ils n’atteignent la prod. Téléchargez Apidog et connectez-le à votre passerelle dès aujourd’hui.

Top comments (0)