DEV Community

Cover image for Como Usar a API Zuplo: Guia Completo
Lucas
Lucas

Posted on • Originally published at apidog.com

Como Usar a API Zuplo: Guia Completo

Se você leu sobre o Zuplo e quer colocar algo real em produção, este guia te mostra como fazer na prática. Aqui você vai criar um projeto, expor uma rota, adicionar autenticação por chave de API e limitação de taxa, escrever uma política TypeScript customizada, fazer deploy para a edge e testar com o Apidog — tudo em passos objetivos para implementação rápida.

Experimente o Apidog hoje

No final, você terá um gateway de API funcional na frente da sua origem, com autenticação, limitação de taxa, portal do desenvolvedor auto-gerado e CI friendly via Git. O passo a passo leva cerca de 30 minutos.

Se ainda está avaliando se o Zuplo é o ideal, comece pelo nosso post complementar: O que é o gateway de API Zuplo. Para cenários não cobertos aqui, confira a documentação do Zuplo.

TL;DR

  • Cadastre-se em portal.zuplo.com ou crie um projeto local com npm create zuplo.
  • Defina rotas em config/routes.oas.json e encaminhe para sua origem via URL Forward Handler.
  • Adicione políticas de entrada (API key auth, rate limit, validação de schema) editando o arquivo de rota ou usando o Route Designer.
  • Escreva lógica customizada como módulos TypeScript em modules/.
  • Faça push para sua branch Git para deploy de preview; merge para produção em mais de 300 edges.
  • Teste todas as rotas com o Apidog antes de promover para produção.
  • O plano gratuito oferece 100 mil requisições/mês; o Builder custa $25/mês.

Pré-requisitos

Você precisa de:

  • Conta Zuplo
  • Uma API de origem (use https://echo.zuplo.io se não tiver uma)
  • Node.js 18+ para usar o CLI

Para desenvolvimento local, use um editor de código. VS Code com TypeScript é recomendado, e pode ser integrado com a extensão Apidog VS Code.

Passo 1: Crie seu projeto Zuplo

Duas formas de começar: via portal web ou CLI.

Opção A: Portal

  1. Faça login em portal.zuplo.com.
  2. Clique em "New Project" e escolha um nome, ex: acme-gateway.
  3. Selecione "Empty Project" para não gerar nada automaticamente.
  4. A aba "Code" mostra a estrutura inicial.

Estrutura inicial do projeto no portal

O portal já vincula a um repositório Git, que pode ser conectado ao seu GitHub, GitLab, Bitbucket ou Azure DevOps depois.

Opção B: CLI

O CLI prepara o projeto local para editar na IDE e usar Git desde o início:

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

O dev server inicia na porta 9000 e o Route Designer local em http://localhost:9100.

Para vincular ao seu Zuplo e fazer deploy:

npx zuplo link
Enter fullscreen mode Exit fullscreen mode

Escolha conta/ambiente. Depois, use:

npx zuplo deploy
Enter fullscreen mode Exit fullscreen mode

Passo 2: Defina sua primeira rota

Abra config/routes.oas.json e adicione a rota que faz proxy para sua origem:

{
  "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
  • x-zuplo-route define handler e políticas.
  • ${env.ORIGIN_URL} usa variável de ambiente. Defina em Settings > Environment Variables no portal ou em config/.env local.

Salve e teste em http://localhost:9000/v1/products.

Passo 3: Adicione autenticação por chave de API

Para proteger APIs públicas, use a política de API key do Zuplo.

No arquivo da rota, adicione:

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

Depois, defina a política em 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

Crie um consumidor (usuário de chave):

  1. No portal: Services > API Key Service.
  2. Clique em "Create Consumer".
  3. Use um identificador, ex: acme-customer-1, e e-mail do responsável.
  4. Copie a chave gerada.

Teste:

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

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

Se preferir usar cliente real, importe a OpenAPI no Apidog, defina header global Authorization: Bearer {{api_key}} e vincule a variável.

Passo 4: Limite a taxa da rota

Para evitar abusos, adicione rate limit logo após a autenticação:

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

Em 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" limita por cliente autenticado.
  • Troque para "ip" se quiser limitar por IP.

Teste com 70 requisições rápidas:

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 SUA_API_KEY"
done | sort | uniq -c
Enter fullscreen mode Exit fullscreen mode

Espere 60 respostas 200 e 10 de 429.

Passo 5: Valide payloads de requisição

Para rotas POST, use validação automática via JSON Schema na OpenAPI.

Exemplo de rota:

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

Política em 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

Teste no Apidog com casos: sucesso, campo ausente, enum inválido. Execute todos em um clique.

Passo 6: Escreva uma política TypeScript personalizada

Quando precisar de lógica especial, crie uma política customizada.

Exemplo: cabeçalho de cache variando por plano.

Crie 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

Defina em 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

Referencie na rota:

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

Testes unitários podem ser feitos com Vitest/Jest simulando requests e responses.

Passo 7: Faça o deploy para a edge

Deploy = push Git. Exemplo:

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 cria ambiente de preview para cada branch, com subdomínio separado.

Teste a URL de preview no Apidog. Se tudo ok, faça merge:

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

Em menos de um minuto, a produção é atualizada em mais de 300 edges. Rollback é só revert/push.

Passo 8: Gere o portal do desenvolvedor

Portal automático em https://YOUR-PROJECT.developers.zuplo.com, reconstruído a cada deploy. Inclui:

  • Página por rota, esquema, descrição, console de testes.
  • Exemplos de código para várias linguagens.
  • Emissão de chave de API self-service.
  • Branding customizável em Developer Portal > Settings.

Se sua OpenAPI tem descrições e exemplos, o portal já fica apresentável. Para customizar, clone o código Next.js do repositório do portal Zuplo.

Passo 9: Teste tudo com o Apidog

Garanta qualidade testando todas as rotas, políticas e erros com o Apidog.

Testando APIs com Apidog

Workflow recomendado:

  1. Importe a OpenAPI do gateway de https://YOUR-PROJECT.zuplo.app/openapi no Apidog.
  2. Crie ambientes para local, preview e production, cada um com seu base_url e api_key.
  3. Salve pelo menos três requisições por rota: sucesso, falha de auth, limite de taxa. Rode tudo antes de cada deploy.
  4. Use cenários automatizados do Apidog para encadear chamadas e validar respostas.
  5. Gere exemplos de código e adicione aos runbooks.

Migrando do Postman? Siga o guia de migração. Baixe o Apidog se ainda não tiver.

Perguntas comuns sobre o uso do Zuplo

Como alternar uma rota entre ambientes sem alterar a especificação?

Use variáveis de ambiente. Defina ORIGIN_URL por ambiente (portal ou config/.env), e referencie como ${env.ORIGIN_URL} nas opções do handler.

Posso rodar o Zuplo offline?

Sim. npm run dev sobe gateway local na porta 9000 e Route Designer na 9100. Políticas, validação e rate limit funcionam localmente. Apenas o serviço de chave de API é online, mas pode ser usado com npx zuplo link.

Como faço rollback de um deploy ruim?

Use git revert do commit de merge e push. O Zuplo faz deploy do estado anterior. Não existe botão de "rollback" porque o Git é a fonte da verdade.

O que acontece com requisições em andamento durante o deploy?

Deploys são atômicos na edge: requisições em andamento terminam na versão antiga, novas já usam a nova versão. Sem downtime.

Posso usar o Zuplo com gRPC ou WebSockets?

Sim. O urlForwardHandler faz proxy de upgrades WebSocket, e existe handler específico para gRPC. REST e GraphQL têm suporte nativo.

Como expor minha API Zuplo para agentes de IA?

Adicione o MCP Server Handler na rota, referencie sua OpenAPI e selecione operações a expor. Políticas de autenticação e rate limit também se aplicam. Veja a documentação do Zuplo MCP Server.

Quanto custa o gateway em produção?

Plano gratuito cobre 100k requisições/mês. Builder: $25/mês para 1 milhão/mês, adicionais por $100/100k. Enterprise começa em $1.000/mês. Veja preços completos.

Conclusão

Agora você tem um gateway Zuplo funcional com autenticação por chave de API, limitação de taxa, validação de requisição, política TypeScript customizada e portal do desenvolvedor — tudo versionado e implantado via Git, pronto para CI/CD e ambientes de preview e produção.

O que mantém seu gateway robusto é o ciclo de testes. Use o Apidog em cada preview antes do merge e capture problemas de autenticação, schema ou rate limit antes de irem para produção. Baixe o Apidog e conecte ao seu gateway agora.

Top comments (0)