DEV Community

Cover image for Cómo Usar la API de Zuplo
Roobia
Roobia

Posted on • Originally published at apidog.com

Cómo Usar la API de Zuplo

Si has leído sobre Zuplo y quieres implementar algo real con él, esta es la publicación para ti. La plataforma es rápida de aprender, pero la documentación está dispersa en flujos del portal, comandos de CLI y artículos del centro de aprendizaje. Esta guía une las piezas en un solo tutorial: crear un proyecto, exponer una ruta, agregar autenticación con clave API y limitación de velocidad, escribir una política personalizada de TypeScript, desplegar en el edge y probar todo con Apidog.

Prueba Apidog hoy

Al final, tendrás una puerta de enlace API funcional ejecutándose frente a tu origen, con autenticación, limitación de velocidad, un portal para desarrolladores autogenerado y un flujo de trabajo Git compatible con CI. Todo el recorrido te llevará unos treinta minutos.

Si aún estás decidiendo si Zuplo es la herramienta adecuada, comienza con nuestra publicación complementaria: Qué es la puerta de enlace API de Zuplo. Para todo lo demás, la documentación de Zuplo cubre casos especiales que esta guía omite.

En resumen

  • Regístrate en portal.zuplo.com o andamia un proyecto local con npm create zuplo.
  • Define rutas en config/routes.oas.json y reenvíalas a tu origen con el Manejador de Reenvío de URL (URL Forward Handler).
  • Agrega políticas de entrada (autenticación con clave API, límite de velocidad, validación de esquema) editando el archivo de ruta o haciendo clic en el Diseñador de Rutas.
  • Escribe lógica personalizada como módulos de TypeScript en modules/; el tiempo de ejecución te da acceso tipado a la solicitud, el contexto y el entorno.
  • Haz push a tu rama de Git vinculada para desplegar un entorno de vista previa; fusiona para enviar a producción en más de 300 ubicaciones edge.
  • Prueba cada ruta con Apidog antes de promover a producción.
  • El precio comienza gratis con 100K solicitudes al mes; el plan Builder cuesta $25 al mes.

Requisitos previos

Necesitas tres cosas antes de empezar:

  • Una cuenta de Zuplo
  • Una API de origen para colocar la puerta de enlace delante. Si no tienes una, usa https://echo.zuplo.io, que replica lo que le envíes.
  • Node.js 18 o superior si planeas usar la CLI.

Para el desarrollo local también necesitas un editor de código. VS Code con la extensión de TypeScript es el camino de menor resistencia, y puedes combinarlo con la extensión de Apidog para VS Code para enviar solicitudes sin salir de tu editor.

Paso 1: Crea tu proyecto Zuplo

Tienes dos formas de empezar: el portal web o la CLI. La mayoría de los equipos comienzan en el portal porque es más rápido para una demostración, y luego migran a la CLI una vez que desean CI/CD.

Opción A: Primero el portal

  1. Inicia sesión en portal.zuplo.com.
  2. Haz clic en "New Project" (Nuevo Proyecto) y elige un nombre como acme-gateway.
  3. Elige "Empty Project" (Proyecto Vacío) para que no se cree nada automáticamente.
  4. La pestaña Código se abre a un árbol de archivos inicial.

imagen-232

El portal vincula el proyecto a un repositorio Git gestionado por defecto. Puedes conectar tu propio repositorio de GitHub, GitLab, Bitbucket o Azure DevOps desde Configuración más tarde.

Opción B: Primero la CLI

La CLI andamia el mismo diseño de proyecto localmente para que puedas editar en tu IDE y usar Git desde el primer día.

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

El servidor de desarrollo se inicia en el puerto 9000 y muestra un enlace al Diseñador de Rutas local en http://localhost:9100. Cualquier cambio que realices en el editor o en el diseñador se recarga automáticamente de inmediato.

Para vincular el proyecto local a tu cuenta Zuplo una vez que estés listo para desplegar:

npx zuplo link
Enter fullscreen mode Exit fullscreen mode

Elige la cuenta y el entorno cuando se te solicite. Desde aquí, npx zuplo deploy despliega la rama Git actual.

Paso 2: Define tu primera ruta

Abre config/routes.oas.json. Este es un documento OpenAPI 3 con extensiones Zuplo para manejadores y políticas. Agrega una ruta que reenvíe GET /v1/products a tu origen:

{
  "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
  • La extensión x-zuplo-route es donde Zuplo reside dentro de un archivo OpenAPI por lo demás estándar.
  • El handler describe lo que sucede cuando la ruta coincide; urlForwardHandler es el proxy incorporado.
  • La referencia ${env.ORIGIN_URL} extrae de las variables de entorno para que puedas apuntar a diferentes backends por entorno.

Establece ORIGIN_URL desde Configuración > Variables de Entorno en el portal, o editando config/.env localmente. Usa https://echo.zuplo.io si aún no tienes un origen real.

Guarda y el servidor de desarrollo local se recargará. Accede a http://localhost:9000/v1/products y deberías ver la solicitud replicada. Las puertas de enlace desplegadas responderán desde el centro de datos edge más cercano en su lugar.

Paso 3: Agrega autenticación con clave API

Las API públicas necesitan credenciales. Zuplo ofrece un servicio de claves API gestionado para que no tengas que construir un almacén de claves por tu cuenta.

Edita la ruta para agregar la política de entrada:

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

Luego, agrega la definición de la política a config/policies.json (Zuplo crea este archivo la primera vez que agregas una política):

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

Ahora crea un consumidor (la entidad que posee una o más claves API):

  1. Ve a Servicios > Servicio de Claves API en el portal.
  2. Haz clic en "Create Consumer" (Crear Consumidor).
  3. Establece el sujeto a un identificador estable como acme-customer-1.
  4. Agrega el correo electrónico de quien deba gestionar la clave.
  5. Copia la clave API generada.

Prueba con curl. Sin la cabecera, deberías ver un 401:

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

Con la cabecera, deberías ver la respuesta original 200:

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

Si prefieres manejar esto desde un cliente real, importa la especificación OpenAPI de la puerta de enlace en Apidog, establece una cabecera global para Authorization: Bearer {{api_key}}, y vincula api_key a una variable de entorno. Obtendrás una superficie de prueba limpia para cada ruta en segundos.

Paso 4: Limita la velocidad de la ruta

Nunca lances una API pública sin límites de velocidad. La política predeterminada de límite de velocidad de Zuplo te ofrece limitación por IP, por clave o por atributo personalizado.

Agrégala a la lista de entrada, después de la autenticación:

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

Defínela en 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" asocia el cubo al sujeto autenticado de la política de claves API, de modo que cada cliente obtiene su propio presupuesto de 60 por minuto. Reemplaza con "ip" si quieres limitar el tráfico anónimo.

La solicitud número 61 dentro de cualquier ventana de sesenta segundos devuelve un 429 con cabeceras de reintento adjuntas. Pruébalo enviando 70 solicitudes en un bucle y observando cómo cambian los códigos de respuesta.

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

Deberías ver 60 líneas que indican 200 y 10 que indican 429.

Paso 5: Valida las cargas útiles de las solicitudes

Si tienes una ruta POST que acepta un cuerpo JSON, la política de validación de solicitudes detecta cargas útiles malformadas en la puerta de enlace en lugar de en tu origen. Utiliza el esquema JSON incrustado en tu operación OpenAPI, por lo que obtienes esto gratis si tu especificación es precisa.

Agrega una ruta con un cuerpo de solicitud:

"/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": { /* mismo que arriba */ },
      "policies": {
        "inbound": [
          "api-key-auth",
          "rate-limit-by-key",
          "validate-request"
        ]
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Agrega la política:

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

Ahora, una solicitud POST con un campo faltante será rechazada con un 400 antes de que llegue a tu origen. Pruébalo con Apidog guardando una solicitud de “ruta feliz”, una solicitud de “campo requerido faltante” y una solicitud de “valor de enumeración incorrecto” como ejemplos separados en el mismo grupo de solicitudes. Puedes ejecutar las tres con un solo clic.

Paso 6: Escribe una política personalizada de TypeScript

Las políticas predefinidas cubren la mayoría de las necesidades de los equipos. El objetivo de Zuplo, sin embargo, es el momento en que necesitas algo personalizado. Aquí tienes una política de salida que agrega una cabecera Cache-Control para clientes de pago y no-store para los gratuitos.

Crea 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

Conéctala en 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

Y referénciala desde la ruta:

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

La política personalizada es solo una función. Puedes probarla unitariamente con Vitest o Jest pasando un Response y ZuploRequest sintéticos y haciendo aserciones sobre las cabeceras, sin necesidad de un arnés de integración.

Paso 7: Despliega en el edge

El despliegue es un git push.

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 construye un entorno de vista previa para cada rama e imprime la URL en el registro de compilación. La vista previa obtiene su propio subdominio como https://acme-gateway-feature-products-gateway-abc123.zuplo.app, con todas tus políticas activas y apuntando a cualquier ORIGIN_URL que esté configurado para ese entorno.

Prueba la URL de vista previa con Apidog configurándola como un nuevo entorno en tu proyecto. Ejecuta tu suite de pruebas completa contra ella. Si todo pasa, fusiona la rama.

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

La fusión dispara el despliegue a producción. En sesenta segundos, la nueva versión está activa en más de 300 ubicaciones edge. La promoción y la reversión son ambas operaciones git push; no hay una interfaz de usuario separada.

Paso 8: Genera el portal para desarrolladores

El portal se aloja en https://YOUR-PROJECT.developers.zuplo.com y se reconstruye en cada despliegue. Incluye:

  • Una página por ruta, con el esquema, la descripción y una consola de prueba.
  • Ejemplos de código en cURL, JavaScript, Python, Go y algunos otros.
  • Emisión de claves API de autoservicio para cualquier visitante que se registre.
  • Controles de marca en el portal bajo Portal para desarrolladores > Configuración.

Si tu especificación OpenAPI tiene buenas descripciones y ejemplos, el portal parecerá terminado sin más trabajo. Si tu especificación es escasa, este es el momento en que lo descubrirás.

Para personalizar, el código fuente del portal se envía como una aplicación Next.js separada que puedes bifurcar desde el repositorio del portal para desarrolladores de Zuplo en GitHub. La mayoría de los equipos se mantienen en la versión alojada.

Paso 9: Prueba todo con Apidog

Una vez que tu puerta de enlace esté activa, la disciplina que previene incidentes en producción es probar cada ruta, cada política y cada ruta de error. Apidog lo hace rápido.

imagen-233

El flujo de trabajo que funciona bien:

  1. Importa la especificación OpenAPI de la puerta de enlace desde https://YOUR-PROJECT.zuplo.app/openapi. Apidog convierte cada operación en una solicitud que puedes enviar.
  2. Crea entornos para local, preview y production, cada uno con su propia base_url y api_key.
  3. Guarda como mínimo tres solicitudes por ruta: ruta feliz, fallo de autenticación y activación del límite de velocidad. Ejecútalas como un grupo antes de cada despliegue.
  4. Usa los escenarios de prueba automatizados de Apidog para encadenar llamadas (crear un producto, listarlo, eliminarlo) y hacer aserciones sobre las formas de las respuestas.
  5. Genera ejemplos de código en el lenguaje principal de tu equipo y pégalos en tus manuales de operaciones.

Si estás migrando desde Postman, la guía de prueba de API sin Postman te explica la importación. Descarga Apidog si aún no lo has hecho.

Preguntas frecuentes sobre el uso de Zuplo

¿Cómo cambio una ruta entre entornos sin modificar la especificación?

Usa variables de entorno. Define ORIGIN_URL por entorno en la Configuración del portal o en config/.env localmente, y referénciala como ${env.ORIGIN_URL} dentro de las opciones del manejador. La ruta permanece idéntica; solo la variable cambia.

¿Puedo ejecutar Zuplo sin conexión?

Sí. npm run dev inicia una puerta de enlace local en el puerto 9000 con el Diseñador de Rutas local en el 9100. Las políticas personalizadas, la validación y la limitación de velocidad funcionan todas localmente; lo único que requiere una conexión a Internet es el servicio gestionado de claves API, y puedes ejecutar npx zuplo link para usar el servicio en la nube desde tu instancia local.

¿Cómo revierto un despliegue defectuoso?

Haz git revert al commit de fusión y haz push. Zuplo redeploya el estado anterior. No hay un botón de “reversión” separado porque el historial de Git es la fuente de la verdad.

¿Qué sucede con las solicitudes en curso durante un despliegue?

Los despliegues son atómicos en el edge; las solicitudes en curso terminan en la versión antigua y las nuevas solicitudes llegan a la nueva versión. No hay ventana de inactividad.

¿Puedo usar Zuplo con gRPC o WebSockets?

Sí. El urlForwardHandler proxy las actualizaciones de WebSocket de forma transparente, y gRPC es compatible a través del manejador gRPC. REST y GraphQL son de primera clase y los casos más comunes.

¿Cómo expongo mi API de Zuplo a agentes de IA?

Agrega el Manejador del Servidor MCP a una ruta, apúntalo a tu especificación OpenAPI y elige las operaciones a exponer. Las mismas políticas de autenticación y límite de velocidad se aplican a las solicitudes MCP. La documentación del Servidor MCP de Zuplo cubre la configuración.

¿Cuánto cuesta la puerta de enlace en producción?

El nivel gratuito cubre 100K solicitudes por mes. El plan Builder agrega 1M de solicitudes por $25 al mes, y las solicitudes adicionales cuestan $100 por cada 100K. Los precios empresariales comienzan en $1,000 al mes con un contrato anual. Desglose completo en la página de precios de Zuplo.

Conclusión

Ahora tienes una puerta de enlace Zuplo funcional con autenticación de clave API, limitación de velocidad por clave, validación de solicitudes, una política de salida personalizada de TypeScript y un portal para desarrolladores, todo desplegado a través de Git al edge global. El mismo proyecto maneja entornos de vista previa, lanzamientos de producción y acceso de agentes de IA a través de MCP.

La pieza que lo mantiene estable es el ciclo de pruebas. Usa Apidog en cada vista previa antes de fusionarla, y detectarás las cabeceras de autenticación rotas, los campos de esquema faltantes y los límites de velocidad que fueron accidentalmente demasiado generosos antes de que se implementen. Descarga Apidog y conéctalo a tu puerta de enlace hoy.

Top comments (0)