DEV Community

Cover image for O que é httpbin? Endpoints, Como Usar e Alternativas
Lucas
Lucas

Posted on • Originally published at apidog.com

O que é httpbin? Endpoints, Como Usar e Alternativas

Se você precisa testar um cliente HTTP sem depender de um backend real, o httpbin é uma das opções mais simples: ele recebe sua requisição e devolve um JSON descrevendo exatamente o que chegou ao servidor. Isso ajuda a validar headers, payloads, autenticação, timeouts, redirecionamentos e tratamento de erros. Você pode usá-lo com curl, com um cliente visual como o Apidog ou diretamente em código. O projeto está disponível em httpbin.org e é open source sob licença ISC.

Experimente o Apidog hoje

O que é httpbin?

httpbin é um serviço HTTP de requisição e resposta. Você envia uma requisição; ele responde com um JSON contendo detalhes do que recebeu: método, headers, query params, corpo, IP de origem e outros dados dependendo do endpoint.

Ele foi criado por Kenneth Reitz, desenvolvedor da biblioteca requests do Python, e é escrito em Python com Flask.

O principal valor do httpbin é funcionar como um “espelho” da sua requisição. Por exemplo, se você quer confirmar se seu cliente está enviando corretamente o header User-Agent, basta chamar:

curl https://httpbin.org/headers
Enter fullscreen mode Exit fullscreen mode

A resposta lista os headers recebidos pelo servidor. Não há banco de dados, login ou configuração: apenas uma forma rápida de inspecionar o que seu cliente HTTP realmente enviou.

A instância pública httpbin.org é útil para testes rápidos, mas pode ficar lenta ou indisponível por ser um serviço gratuito e compartilhado. A manutenção do projeto mudou ao longo dos anos; o código está no repositório postmanlabs/httpbin no GitHub, e há forks da comunidade, como o da Kong. Para uso frequente, especialmente em CI, prefira hospedar sua própria instância.

Endpoints principais do httpbin

Use estes endpoints como blocos de teste para validar comportamentos específicos do seu cliente HTTP.

Endpoint O que ele faz
/get Retorna query params, headers e IP de origem de uma requisição GET
/post Retorna dados de formulário, corpo JSON e headers enviados via POST
/put, /patch, /delete Faz o mesmo tipo de eco para outros métodos HTTP
/status/{codes} Retorna o status informado, como /status/404 ou /status/503
/headers Retorna apenas os headers recebidos
/ip Retorna seu IP de origem
/user-agent Retorna o User-Agent enviado pelo cliente
/delay/{n} Aguarda n segundos antes de responder, até 10 segundos
/basic-auth/{user}/{passwd} Retorna 200 apenas com credenciais Basic Auth corretas
/bearer Verifica se há um token Bearer no header Authorization
/redirect/{n} Executa n redirecionamentos
/cookies Retorna os cookies enviados pelo cliente
/uuid Retorna um UUID aleatório
/anything Ecoa praticamente tudo sobre a requisição, independentemente do método

Os endpoints mais úteis para testes de resiliência são /status/{codes} e /delay/{n}. Com eles, você força erros e lentidão sob demanda, algo difícil de reproduzir de forma controlada em uma API real.

Se você precisa de respostas falsas com estrutura de domínio, e não apenas eco da requisição, combine o httpbin com uma API falsa para dados de teste.

Como usar o httpbin na prática

1. Validar query params e headers com GET

Envie uma requisição GET simples:

curl "https://httpbin.org/get?tool=apidog&check=headers"
Enter fullscreen mode Exit fullscreen mode

A resposta inclui campos como:

{
  "args": {
    "check": "headers",
    "tool": "apidog"
  },
  "headers": {
    "Accept": "*/*",
    "Host": "httpbin.org",
    "User-Agent": "curl/..."
  },
  "origin": "..."
}
Enter fullscreen mode Exit fullscreen mode

Use isso para confirmar se:

  • os query params foram serializados corretamente;
  • os headers esperados chegaram ao servidor;
  • o cliente está enviando o User-Agent correto;
  • proxies ou gateways estão alterando a requisição.

2. Validar envio de JSON com POST

Para testar um corpo JSON:

curl -X POST "https://httpbin.org/post" \
  -H "Content-Type: application/json" \
  -d '{"name": "widget", "qty": 3}'
Enter fullscreen mode Exit fullscreen mode

O httpbin devolve o JSON interpretado, o corpo bruto e os headers recebidos. Verifique especialmente:

  • se o Content-Type chegou como application/json;
  • se o payload não foi alterado;
  • se o cliente está serializando números, strings e objetos como esperado.

3. Forçar erros HTTP

Para testar o tratamento de erro do seu cliente:

curl -i "https://httpbin.org/status/503"
Enter fullscreen mode Exit fullscreen mode

Você receberá uma resposta real 503 Service Unavailable.

Use variações para cobrir cenários comuns:

curl -i "https://httpbin.org/status/400"
curl -i "https://httpbin.org/status/401"
curl -i "https://httpbin.org/status/404"
curl -i "https://httpbin.org/status/429"
curl -i "https://httpbin.org/status/500"
Enter fullscreen mode Exit fullscreen mode

Isso é útil para validar:

  • retry automático;
  • circuit breakers;
  • mensagens de erro;
  • fallback;
  • logging;
  • métricas de falha.

4. Simular timeout ou API lenta

Para atrasar a resposta em 5 segundos:

curl -i "https://httpbin.org/delay/5"
Enter fullscreen mode Exit fullscreen mode

Use esse endpoint para confirmar se o timeout do cliente está configurado corretamente.

Exemplo com curl limitando o tempo máximo:

curl --max-time 2 "https://httpbin.org/delay/5"
Enter fullscreen mode Exit fullscreen mode

Nesse caso, o cliente deve abortar a requisição antes da resposta.

5. Testar autenticação Basic Auth

Endpoint:

https://httpbin.org/basic-auth/{user}/{passwd}
Enter fullscreen mode Exit fullscreen mode

Exemplo:

curl -i -u admin:secret "https://httpbin.org/basic-auth/admin/secret"
Enter fullscreen mode Exit fullscreen mode

Com credenciais corretas, a resposta retorna sucesso. Com credenciais incorretas, você recebe erro de autenticação.

6. Testar Bearer Token

Para verificar se o header Authorization está sendo enviado:

curl -i "https://httpbin.org/bearer" \
  -H "Authorization: Bearer meu-token"
Enter fullscreen mode Exit fullscreen mode

Esse teste ajuda a confirmar se interceptors, middlewares ou wrappers HTTP estão anexando o token corretamente.

7. Testar redirecionamentos

Para simular três redirecionamentos:

curl -i -L "https://httpbin.org/redirect/3"
Enter fullscreen mode Exit fullscreen mode

Sem -L, o curl mostra apenas a resposta de redirecionamento. Com -L, ele segue os redirects.

Use isso para validar:

  • limite máximo de redirecionamentos;
  • preservação ou remoção de headers;
  • comportamento entre HTTP e HTTPS;
  • logs de navegação entre URLs.

Usando httpbin com Apidog

Você não precisa ficar no terminal. Qualquer cliente REST pode chamar os mesmos endpoints.

No Apidog, por exemplo:

  1. Crie uma nova requisição.
  2. Defina o método, como GET ou POST.
  3. Use uma URL do httpbin, por exemplo: 
   https://httpbin.org/get
Enter fullscreen mode Exit fullscreen mode
  1. Adicione headers, query params ou body.
  2. Envie a requisição.
  3. Inspecione a resposta formatada.
  4. Salve o teste para repetir depois.

Esse fluxo é útil quando você quer:

  • comparar respostas entre ambientes;
  • compartilhar uma requisição com outra pessoa;
  • salvar exemplos de erro;
  • adicionar variáveis de ambiente;
  • transformar chamadas manuais em testes repetíveis.

Se preferir trabalhar no terminal, veja também estes clientes de API REST TUI.

Hospedando httpbin com Docker

A instância pública httpbin.org é prática, mas não é ideal para pipelines, testes automatizados ou ambientes privados. Para isso, execute sua própria instância com Docker.

Baixe a imagem:

docker pull kennethreitz/httpbin
Enter fullscreen mode Exit fullscreen mode

Execute o container na porta 80:

docker run -p 80:80 kennethreitz/httpbin
Enter fullscreen mode Exit fullscreen mode

Agora teste localmente:

curl "http://localhost/get"
Enter fullscreen mode Exit fullscreen mode

Você terá o mesmo comportamento da instância pública, mas sem depender de um serviço externo.

A imagem está disponível no Docker Hub como kennethreitz/httpbin.

Se a porta 80 já estiver em uso, mapeie outra porta:

docker run -p 8080:80 kennethreitz/httpbin
Enter fullscreen mode Exit fullscreen mode

E chame:

curl "http://localhost:8080/get"
Enter fullscreen mode Exit fullscreen mode

Para CI, prefira apontar seus testes para essa instância local ou interna. Isso reduz flakiness causado por rede, rate limits ou indisponibilidade da instância pública.

Exemplo: teste automatizado simples com httpbin

Você pode usar httpbin para validar rapidamente se seu cliente lida bem com status codes.

Exemplo em JavaScript com fetch:

async function requestWithStatusCheck(url) {
  const response = await fetch(url);

  if (!response.ok) {
    throw new Error(`HTTP error: ${response.status}`);
  }

  return response.json();
}

requestWithStatusCheck("https://httpbin.org/status/500")
  .then(console.log)
  .catch((error) => {
    console.error("Falha tratada:", error.message);
  });
Enter fullscreen mode Exit fullscreen mode

Esse tipo de teste ajuda a validar se sua aplicação:

  • identifica response.ok === false;
  • não tenta fazer parse de JSON quando não há corpo;
  • registra erros corretamente;
  • aciona fallback ou retry quando necessário.

Alternativas ao httpbin

httpbin é excelente para ecoar requisições, mas não substitui uma plataforma completa de testes ou mocks. Escolha a alternativa conforme o cenário.

Postman Echo

O Postman Echo é um serviço hospedado com proposta semelhante ao httpbin. Você chama:

https://postman-echo.com/get
Enter fullscreen mode Exit fullscreen mode

E recebe sua requisição espelhada de volta.

Ele cobre endpoints GET, POST, autenticação e utilitários. Consulte a documentação do Postman Echo para a lista completa.

Se httpbin.org estiver indisponível, o Echo pode servir como alternativa rápida.

httpbin auto-hospedado

Se você precisa dos mesmos endpoints, mas com mais controle, use a imagem Docker do httpbin.

Essa é a melhor opção quando:

  • os testes rodam em CI;
  • a rede é privada;
  • você não quer depender de serviços externos;
  • precisa de comportamento previsível.

Serviços de mock

httpbin ecoa a requisição. Ele não retorna dados realistas de domínio, como usuários, pedidos ou resultados paginados.

Quando você precisa de respostas falsas, mas estruturadas, use um servidor de mock. O Apidog possui mocking inteligente integrado que gera respostas a partir do seu esquema, permitindo que o frontend desenvolva contra endpoints antes de o backend estar pronto.

Apidog como cliente e camada de teste

httpbin é o alvo que recebe requisições. Apidog é a ferramenta para criar, enviar, salvar e automatizar essas requisições.

Você pode usar o Apidog para:

  • chamar endpoints do httpbin;
  • organizar coleções de requisições;
  • configurar variáveis de ambiente;
  • escrever asserções;
  • encadear requisições em cenários;
  • executar testes em CI;
  • substituir chamadas ad-hoc por fluxos repetíveis.

Os dois não são equivalentes: httpbin é um serviço simples de eco; Apidog é a bancada de trabalho em volta do ciclo de API.

Para mais opções sem instalação, veja estas ferramentas de teste de API online gratuitas.

FAQ

O httpbin é gratuito?

Sim. A instância pública httpbin.org é gratuita e não exige conta. O código-fonte é aberto sob licença ISC, então você também pode executá-lo por conta própria sem custo.

O httpbin ainda é mantido?

A base de código está no repositório postmanlabs/httpbin do GitHub e recebe alguma atenção contínua, embora a manutenção tenha sido intermitente. Como httpbin.org pode ficar instável, muitas equipes usam uma cópia Docker auto-hospedada para testes importantes.

Posso usar httpbin para testar webhooks?

Não exatamente. O httpbin ecoa requisições enviadas para ele, mas não recebe eventos de terceiros e os encaminha para sua máquina local.

Para isso, use um serviço dedicado de tunelamento ou inspeção. Veja este guia sobre testar APIs e webhooks locais e este guia sobre como os webhooks funcionam.

Qual é a diferença entre httpbin e Postman Echo?

Eles têm funções parecidas: ambos ecoam uma requisição HTTP como JSON.

A diferença principal é a origem e hospedagem. httpbin é o serviço open source original em Python e Flask; Postman Echo é um serviço hospedado pelo Postman. Na prática, use o que estiver disponível e acessível no seu ambiente.

Posso testar tratamento de erros com httpbin?

Sim. Use /status/{code} para forçar códigos como:

/status/500
/status/429
/status/404
Enter fullscreen mode Exit fullscreen mode

E use /delay/{n} para simular respostas lentas:

/delay/5
Enter fullscreen mode Exit fullscreen mode

Esses endpoints são úteis para testar retry, timeout, fallback e mensagens de erro.

Conclusão

httpbin é uma ferramenta simples e direta para validar clientes HTTP. Use:

  • /get e /post para confirmar query params, headers e payloads;
  • /headers para inspecionar headers recebidos;
  • /status/{code} para forçar erros;
  • /delay/{n} para testar timeouts;
  • Docker para executar uma instância privada e previsível em CI.

Quando você precisar ir além do eco da requisição, adicione mocks realistas, testes salvos e asserções automatizadas.

O Apidog pode ser usado como cliente para chamar o httpbin, como camada de mocking para substituí-lo e como plataforma de testes para transformar verificações manuais em fluxos repetíveis. Baixe o Apidog e evolua seus testes com httpbin para uma rotina automatizada.

Top comments (0)