DEV Community

Cover image for Como Hospedar um Servidor Mock na Nuvem Compartilhável com Apidog
Lucas
Lucas

Posted on • Originally published at apidog.com

Como Hospedar um Servidor Mock na Nuvem Compartilhável com Apidog

Sua equipe de frontend está bloqueada: o design foi aprovado, as telas já começaram a ser construídas, mas a API ainda está a um sprint de distância. Um mock local resolve o problema apenas enquanto a máquina que o executa está ligada. Quando você fecha o laptop, o endpoint deixa de existir para QA, colegas em outros fusos horários e parceiros externos.

Experimente o Apidog hoje

O Apidog resolve essa lacuna com o Cloud Mock: uma URL pública em mock.apidog.com que continua disponível independentemente da sua máquina. Assim, frontend, QA e parceiros podem consumir respostas realistas antes da implementação do backend. Para o contexto geral, veja o que é um mock de API e quando usá-lo. Para revisar o fluxo de requisição e resposta, consulte a referência HTTP da MDN.

O que é o Cloud Mock e por que mocks locais não bastam

Para cada API projetada, o Apidog gera um endpoint de mock. Por padrão, ele é local: responde enquanto a sua instância do Apidog está em execução. Isso funciona para depuração individual, mas falha quando outra pessoa precisa acessar a mesma URL.

O Cloud Mock hospeda esse endpoint no serviço do Apidog. O mock permanece acessível 24 horas por dia, 7 dias por semana, mesmo que seu laptop esteja desligado.

Na prática, o fluxo fica assim:

  1. Você define o contrato da API.
  2. Ativa o Cloud Mock.
  3. Compartilha uma URL pública.
  4. Frontend, QA e parceiros usam o endpoint antes da entrega do backend.

Para equipes distribuídas, veja também as práticas de compartilhamento de mock servers e ambientes com equipes globais.

Habilite o Cloud Mock e obtenha uma URL pública

Vamos usar uma API de usuários com o endpoint GET /users.

Passo 1: ative o Cloud Mock

No Apidog, abra:

Project Settings > Feature Settings > Mock Settings

Ative Cloud Mock.

Você precisa fazer isso apenas uma vez por projeto. Depois disso, cada endpoint passa a ter uma URL de mock na nuvem, além da URL local.

Configuração do Cloud Mock

Passo 2: copie a URL do endpoint

Abra o endpoint GET /users, vá até a aba Mock e copie a URL do Cloud Mock.

Exemplo:

https://mock.apidog.com/m1/2689726-0-default/users?apidogToken=GdfNrEm6lxM9nDGGIMCWC1OPSiZ6hGOi
Enter fullscreen mode Exit fullscreen mode

A URL segue este formato:

mock.apidog.com/m1/<projectId>-<num>-<env>/<path>
Enter fullscreen mode Exit fullscreen mode

Não monte essa URL manualmente. Copie a URL gerada pelo Apidog, pois ela contém os identificadores e parâmetros corretos do projeto.

Passo 3: teste a resposta no Apidog

Ainda na aba Mock, envie uma requisição de teste para o endpoint. Isso permite validar imediatamente se o schema está gerando dados adequados para o consumidor da API.

Uma resposta possível para GET /users:

[
  {
    "id": 1,
    "name": "Amelia Turner",
    "email": "amelia.turner@example.com",
    "city": "Portland"
  },
  {
    "id": 2,
    "name": "Marcus Bell",
    "email": "marcus.bell@example.com",
    "city": "Austin"
  }
]
Enter fullscreen mode Exit fullscreen mode

Os valores são gerados a partir dos nomes e tipos definidos no schema. Isso permite que o frontend trabalhe com dados mais próximos de um cenário real, em vez de valores genéricos como "string".

Passo 4: consuma a URL

Para endpoints GET, você pode abrir a URL diretamente no navegador e verificar o JSON retornado.

No terminal, use curl:

curl "https://mock.apidog.com/m1/2689726-0-default/users?apidogToken=GdfNrEm6lxM9nDGGIMCWC1OPSiZ6hGOi"
Enter fullscreen mode Exit fullscreen mode

No frontend, use a URL como qualquer API HTTP:

const response = await fetch(
  "https://mock.apidog.com/m1/2689726-0-default/users?apidogToken=GdfNrEm6lxM9nDGGIMCWC1OPSiZ6hGOi"
);

const users = await response.json();
Enter fullscreen mode Exit fullscreen mode

Com isso, o ciclo é simples: projete o endpoint, habilite o Cloud Mock, copie a URL e compartilhe-a com a equipe.

Proteja o mock com autenticação por token

Uma URL pública facilita o compartilhamento, mas alguns mocks podem representar recursos ainda não lançados ou integrações que precisam de controle de acesso.

Para exigir autenticação, vá até:

Project Settings > Feature Settings > Mock Settings

Defina a permissão como Token Authentication.

Com essa opção ativa, cada requisição deve incluir um apidogToken válido. Você pode enviá-lo de três formas.

Token na query string 

curl "https://mock.apidog.com/m1/2689726-0-default/users?apidogToken=GdfNrEm6lxM9nDGGIMCWC1OPSiZ6hGOi"
Enter fullscreen mode Exit fullscreen mode

Token no cabeçalho HTTP

Essa abordagem evita incluir o token na URL e em logs que registram URLs completas.

curl "https://mock.apidog.com/m1/2689726-0-default/users" \
  -H "apidogToken: GdfNrEm6lxM9nDGGIMCWC1OPSiZ6hGOi"
Enter fullscreen mode Exit fullscreen mode

Token no corpo da requisição

Também é possível enviar apidogToken como um parâmetro de corpo em requisições form-data ou x-www-form-urlencoded.

No frontend, prefira o cabeçalho:

const response = await fetch(
  "https://mock.apidog.com/m1/2689726-0-default/users",
  {
    headers: {
      apidogToken: "GdfNrEm6lxM9nDGGIMCWC1OPSiZ6hGOi"
    }
  }
);

const users = await response.json();
Enter fullscreen mode Exit fullscreen mode

Se você habilitar a autenticação por token após compartilhar uma URL sem proteção, avise todos os consumidores. Requisições existentes passarão a falhar até que incluam o token.

Gere dados realistas por região com locales

Mocks com valores como "name": "string" validam apenas a estrutura da resposta. Já nomes, endereços e telefones plausíveis ajudam a identificar problemas de layout, truncamento, internacionalização e formatação antes da chegada dos dados reais.

O Apidog usa Faker.js para gerar esses dados. Você pode controlar a localidade em três níveis.

Defina o locale padrão do projeto

O idioma definido em:

Project Settings > Basic Settings

serve como locale padrão para os dados gerados. Por exemplo, ao configurar o projeto para francês, os nomes e endereços de mock passam a refletir esse contexto.

Sobrescreva o locale para todo o projeto

Se o locale dos mocks deve ser diferente do idioma geral do projeto, abra:

Project Settings > Feature Settings > Mock Settings

Selecione um locale do Faker na lista disponível.

Isso é útil para testar internacionalização. Por exemplo, ao usar um locale japonês, sua UI pode ser validada com scripts não latinos e formatos de endereço diferentes. Para entender como o Apidog gera dados a partir do schema, veja o guia sobre smart mock do Apidog e leitura de schemas.

Sobrescreva o locale por campo

Quando apenas um campo precisa usar outra região, defina o parâmetro locale na expressão de mock:

{{$person.fullName(locale='ja')}}
Enter fullscreen mode Exit fullscreen mode

Isso pode gerar um nome como:

田中 太郎
Enter fullscreen mode Exit fullscreen mode

A ordem de precedência é:

  1. Locale definido no campo.
  2. Locale definido nas configurações de mock do projeto.
  3. Idioma padrão em Basic Settings.

A documentação usa ja como exemplo. Confirme os códigos suportados para sua região na documentação de mock do Apidog e na referência de localization do Faker.js.

Configure também o fuso horário

Para timestamps, configure o fuso horário padrão em:

Project Settings > Feature Settings > Mock Settings

Você também pode sobrescrever o valor por campo com o parâmetro timeZone em uma expressão de mock.

Isso é especialmente útil para campos como createdAt, updatedAt e datas de eventos, pois mantém os dados coerentes com a região simulada.

Para mais exemplos de aplicação, veja os casos de uso práticos de mocking de API.

Cloud Mock versus mock auto-hospedado

O Cloud Mock é a alternativa hospedada e atende bem equipes que precisam de uma URL compartilhável sem operar infraestrutura.

Use uma alternativa auto-hospedada quando houver requisitos como:

  • residência de dados;
  • políticas que impedem tráfego de teste em serviços de terceiros;
  • necessidade de operar o mock dentro da própria rede.

A troca é direta:

Opção Vantagem Responsabilidade
Cloud Mock Configuração simples e disponibilidade contínua Gerenciado pelo Apidog
Auto-hospedado Controle sobre infraestrutura e tráfego Sua equipe opera o serviço

Para configurar essa segunda opção, consulte o guia de como auto-hospedar o servidor de mock do Apidog. Para comparar ferramentas hospedadas, veja a comparação de ferramentas de mocking de API online.

A documentação apresentada não indica um requisito específico de plano para os recursos de Cloud Mock e mock local. Verifique a disponibilidade atual diretamente na sua conta. Você pode baixar o Apidog e testar o fluxo completo no seu workspace.

Automatize a validação com o Apidog CLI

O Apidog CLI não inicia nem serve um mock server. O Cloud Mock é gerado e hospedado pelo Apidog a partir dos schemas dos endpoints.

A CLI entra no fluxo para manter os contratos atualizados e validar a implementação real quando o backend estiver pronto.

Por exemplo, ferramentas como Cursor ou Claude Code podem criar ou atualizar endpoints e schemas no projeto. Como o mock usa esses schemas para gerar respostas, manter a especificação atualizada também mantém o mock alinhado à API.

Depois que o backend for implementado, execute os cenários de teste salvos contra um ambiente real:

apidog run -t <scenario_id> -e <env_id> -r cli
Enter fullscreen mode Exit fullscreen mode

Esse comando:

  • executa um cenário de teste salvo;
  • aponta para o ambiente informado;
  • exibe os resultados no terminal.

Em vez de preencher os IDs manualmente, abra o cenário no Apidog e copie o comando gerado, já com -t e -e configurados.

Para integrar isso ao pipeline, consulte o guia de execução do Apidog em um pipeline CI/CD.

FAQ

A URL do Cloud Mock continua funcionando quando fecho o Apidog?

Sim. Esse é o objetivo do Cloud Mock. Diferentemente do mock local, que depende da máquina host, o mock na nuvem é servido pela infraestrutura do Apidog e permanece disponível 24 horas por dia, 7 dias por semana.

Posso abrir a URL do mock diretamente no navegador?

Para requisições GET, sim. Cole a URL completa, incluindo o parâmetro apidogToken quando necessário, e o navegador exibirá a resposta JSON.

Para outros métodos HTTP ou para evitar expor o token no histórico do navegador, use curl, Postman ou o cliente frontend com o token em um cabeçalho.

O que acontece se a requisição não incluir o token?

Quando Token Authentication está ativa, qualquer requisição sem um apidogToken válido é rejeitada.

Envie o token por:

  • query string;
  • cabeçalho HTTP;
  • corpo form-data ou x-www-form-urlencoded.

Como gero dados de mock para um país específico?

Defina o locale em um destes níveis:

  1. Idioma padrão em Basic Settings.
  2. Locale do projeto em Feature Settings > Mock Settings.
  3. Parâmetro locale na expressão de um campo.

Exemplo:

{{$person.fullName(locale='ja')}}
Enter fullscreen mode Exit fullscreen mode

O locale do campo tem prioridade sobre o locale do projeto, que tem prioridade sobre o idioma padrão. Veja também o guia de smart mock.

Devo usar Cloud Mock ou uma ferramenta headless?

Use Cloud Mock quando precisar de um endpoint hospedado, compartilhável e vinculado ao design da API.

Se você precisa de mocks incorporados a uma automação sem interface gráfica, compare as ferramentas de mock de API headless. Uma especificação limpa baseada na OpenAPI Initiative facilita ambos os caminhos.

Conclusão

Um mock local desbloqueia apenas quem está executando o processo. O Cloud Mock transforma o contrato da sua API em uma URL pública em mock.apidog.com, disponível para toda a equipe.

O fluxo de implementação é direto:

  1. Defina o endpoint e o schema.
  2. Ative o Cloud Mock.
  3. Teste a resposta gerada.
  4. Compartilhe a URL.
  5. Proteja o acesso com token, se necessário.
  6. Configure locale e fuso horário para dados mais realistas.

Assim, o frontend deixa de esperar pelo backend e continua evoluindo contra o mesmo contrato que será validado depois pela implementação real. Baixe o Apidog para criar seu primeiro mock compartilhável.

Top comments (0)