O que é uma Mock API? Guia Completo

Uma API mock é uma API falsa que se comporta como uma real. Ela aceita as mesmas requisições, retorna respostas no mesmo formato e reside em uma URL que você pode chamar, mas por trás dessa URL não há um banco de dados real, nenhuma lógica de negócio e nenhum serviço real. A resposta é algo que você definiu antecipadamente.

Isso parece trivial, e a ideia é. O valor vem do que ela permite fazer: construir e testar contra uma interface antes que o que está por trás dela exista ou enquanto a coisa real é muito lenta, muito cara ou muito pouco confiável para ser chamada. Este explicativo define o termo precisamente, separa um mock das coisas com as quais é confundido e apresenta a distinção entre estático e dinâmico que decide como um mock se comporta.

O que realmente é uma API mock

Simplificando, uma API mock é um mapeamento de requisição para resposta. Uma requisição chega. O mock a compara com as regras que você definiu, seleciona uma resposta e a envia de volta. Não há computação intermediária, a menos que você solicite.

Um mock tem três partes. Há a interface: as rotas, métodos e parâmetros que ele aceita, que devem corresponder exatamente à API real. Há a definição da resposta: os corpos, códigos de status e cabeçalhos que ele retorna. E há a lógica de correspondência: como o mock decide qual resposta uma determinada requisição obtém, desde uma simples correspondência de caminho até regras que se ramificam em parâmetros de consulta ou cabeçalhos.

Como a interface corresponde à API real, o código que chama o mock não sabe que é falso. Troque a URL base e o mesmo cliente se comunica com o serviço real. Essa intercambialidade é o objetivo principal. Para um passo a passo prático de como construir um, veja este guia sobre mocking de uma API para testes.

Ajuda ser preciso sobre o que uma API mock não é. Não é um cache, porque um cache armazena respostas reais e um mock as inventa. Não é um sandbox, porque um sandbox de fornecedor executa lógica real e simplificada, enquanto um mock não executa nenhuma lógica. E não é um ambiente de staging, porque staging é uma implantação completa do sistema real. Um mock é mais leve que os três: é apenas a porta de entrada de uma API com respostas predefinidas por trás dela, e nada mais.

Mock versus stub

As pessoas usam “mock” e “stub” de forma intercambiável, mas em testes eles significam coisas diferentes.

Um stub é a ideia mais simples. Ele retorna uma resposta pré-definida a uma chamada e nada mais. Peça por um usuário, ele retorna um usuário fixo. Um stub não tem opinião sobre como foi chamado.

Um mock, no sentido estrito de testes, também verifica a interação. Ele pode afirmar que foi chamado, quantas vezes e com quais argumentos. Um mock pode falhar seu teste porque a chamada estava errada, não apenas fornecer um valor.

No trabalho diário com APIs, a linha é tênue, e “API mock” geralmente abrange ambos. A lição útil: um stub responde, um mock responde e observa. Quando seu teste se preocupa apenas com os dados que seu código recebe, uma resposta estilo stub é suficiente. Quando ele se preocupa se seu código fez a chamada certa da maneira certa, você quer a verificação que um mock verdadeiro adiciona. Para o vocabulário mais amplo, veja a diferença entre validação e verificação.

Mais dois termos estão próximos. Um fake é uma implementação funcional, mas simplificada, como um banco de dados em memória usado no lugar de um real; ele tem lógica, mas em menor quantidade. Um spy envolve um objeto real e registra como ele foi chamado sem alterar seu comportamento. Uma API mock, como o termo é usado no desenvolvimento de APIs, está mais próxima de um stub com verificação opcional, servido via HTTP em uma URL real. Você não precisa policiar o vocabulário, mas conhecer o espectro ajuda a ler a documentação de testes sem se perder.

API Mock versus servidor real

Um servidor real e um servidor mock podem residir na mesma URL e retornar o mesmo JSON, então a diferença está no que acontece por trás do endpoint.

Um servidor real diz a verdade: ele executa o código real e prova que o sistema funciona. Ele também é lento, mantém estado e é capaz de efeitos colaterais reais, então um teste contra ele pode cobrar um cartão ou enviar um e-mail.

Um servidor mock apenas diz o que você mandou. Ele é rápido, livre de efeitos colaterais e perfeitamente previsível, o que o torna ideal para desenvolvimento e a maioria dos testes. Mas um mock pode estar errado e nunca saber, porque ele não executa a lógica real. É por isso que você mantém alguns testes no servidor real. A compensação é abordada em detalhes em servidor mock versus servidor real.

Mocks estáticos e dinâmicos

Um mock retorna sua resposta de uma de duas maneiras, e a escolha molda como o mock é percebido ao usar.

Um mock estático retorna um payload fixo. Você escreve o JSON exato uma vez, e cada requisição correspondente recebe o mesmo corpo idêntico de volta. Mocks estáticos são previsíveis, o que os torna fáceis de usar para asserções. Sua fraqueza é o realismo: um único payload codificado não irá revelar um bug em um código que falha em strings longas, arrays vazios ou nulos inesperados.

Um mock dinâmico gera a resposta por requisição. Em vez de um fixo "id": "user_1001", ele produz um UUID novo a cada chamada. Em vez de um nome, ele retorna um nome realista diferente a cada vez. Mocks dinâmicos geralmente impulsionam isso com uma gramática de geração de dados como Faker.js, de modo que um campo chamado email gera um e-mail e created_at gera uma data. Eles são mais realistas e melhores em expor casos extremos, ao custo de serem mais difíceis de usar para asserções exatas.

A maioria das equipes usa ambos. Mocks estáticos para testes unitários com muitas asserções onde você precisa de um valor conhecido. Mocks dinâmicos para desenvolvimento, demonstrações e cobertura estilo fuzz onde a variedade importa mais do que uma resposta fixa.

Um mock dinâmico também pode ser condicional, o que é um passo além da geração simples. Um mock condicional se ramifica na requisição: uma requisição para /orders/404 retorna um 404, uma requisição com um token inválido retorna um 401, e todo o resto retorna um 200 normal. Um único endpoint mock, então, cobre o caminho feliz e vários caminhos de falha de uma só vez. É isso que torna um mock genuinamente útil para testes, porque ele pode reproduzir as respostas de erro que um servidor real saudável não produziria sob demanda.

Onde uma API mock se encaixa no desenvolvimento

Uma API mock é útil em três momentos. No início, ela permite que as equipes de frontend e backend concordem com um contrato e construam em paralelo, de modo que nenhuma espere pela outra. Durante os testes, ela isola seu código de instabilidades de rede e permite que você acione respostas de erro que um servidor real não produziria sob demanda. E para demonstrações e protótipos, ela fornece dados controlados e previsíveis, sem dependência em tempo real para falhar no meio da apresentação. Esses cenários são explorados em mais detalhes neste guia sobre casos de uso de mocking de API.

O risco recorrente é a divergência. Um mock é um instantâneo de uma interface, e as interfaces mudam. Quando a API real adiciona um campo ou renomeia um, um mock desconectado continua servindo o formato antigo e seus testes passam contra um contrato que não existe mais.

A solução é tratar o mock como derivado, não como autoral. Gere-o a partir do mesmo esquema que a API real publica, para que uma mudança no contrato regenere o mock. Um mock que você digitou manualmente é uma cópia que começa a envelhecer imediatamente; um mock gerado a partir da especificação é sempre um instantâneo atual. A diferença não aparece no primeiro dia, mas decide se o mock ainda será confiável seis meses depois. Apidog funciona assim: você projeta a API uma vez, e o endpoint mock é gerado a partir desse projeto com dados realistas inferidos dos nomes dos campos. O mock, a documentação e o teste de contrato de API, todos leem de uma única fonte, para que permaneçam em sincronia. Para ver o fluxo de design para mock de ponta a ponta, Baixe o Apidog.

Perguntas frequentes

O que é uma API mock em termos simples?

Uma API mock é uma API falsa que imita uma real. Ela expõe as mesmas rotas e retorna respostas no mesmo formato, mas não há lógica real ou banco de dados por trás dela. As respostas são predefinidas, o que permite construir e testar contra a interface antes que o serviço real exista.

Qual a diferença entre um mock e um stub?

Um stub retorna uma resposta pré-definida e nada mais. Um mock, no sentido estrito de testes, também verifica a interação, então ele pode checar se foi chamado o número correto de vezes com os argumentos certos. Um stub responde; um mock responde e observa.

Como uma API mock é diferente de um servidor real?

Um mock retorna respostas predefinidas sem computação real, então é rápido, previsível e não tem efeitos colaterais. Um servidor real executa lógica real contra um banco de dados real, então é mais lento e mantém estado, mas prova que o sistema realmente funciona. Use um mock para desenvolvimento e o servidor real para testes de contrato e ponta a ponta.

Devo usar um mock estático ou dinâmico?

Use um mock estático quando precisar de um valor previsível para asserções, o que se adequa a testes unitários. Use um mock dinâmico quando quiser dados realistas e variados que capturem casos extremos, o que se adequa a desenvolvimento e demonstrações. Muitas equipes usam ambos.

Como evito que uma API mock se torne imprecisa?

Gere o mock a partir do mesmo esquema que a API real publica, em vez de escrevê-lo manualmente. Quando o contrato muda, o mock é regenerado. Complementar isso com testes de contrato agendados contra a API real detecta qualquer divergência restante precocemente.