O que é httpYac?

Se você pesquisou por httpYac, provavelmente quer uma forma de enviar requisições HTTP de arquivos de texto simples que você pode manter no Git, executar dentro do VS Code e reproduzir na CI. httpYac é exatamente isso: um executor de arquivos .http/.rest que é fornecido tanto como uma extensão do VS Code quanto como uma ferramenta de linha de comando Node.js. Este guia explica como funciona, mostra um pequeno exemplo, aborda quando é adequado e aponta para uma interface gráfica (GUI) e um caminho de CI quando você superar os arquivos de texto. Para um conhecimento mais amplo na disciplina, consulte nosso guia de teste de API.

O que httpYac realmente é

httpYac é um cliente HTTP de código aberto construído em torno do formato de arquivo .http. Você escreve requisições como texto simples e as envia com um atalho de teclado no editor ou com um único comando no seu terminal. O projeto reside no GitHub e possui documentação completa em httpyac.github.io.

A ideia central é simples. Uma requisição reside em um arquivo de texto ao lado do seu código. Você a versiona com o Git. Você a revisa em um pull request. Você a executa da mesma forma, seja você um humano em um editor ou um trabalho de CI em um servidor de build. Esse modelo nativo do Git, em texto simples, é a maior força do httpYac, e é a razão pela qual muitos desenvolvedores de backend o procuram.

Duas partes compõem a ferramenta:

• A **extensão do VS Code** (httpYac) oferece um code lens "Send Request" (Enviar Requisição) acima de cada requisição, pré-visualizações de resposta e alternância de ambiente dentro do editor.
• A **CLI** (httpyac, instalada via npm) executa os mesmos arquivos sem interface gráfica (headless). Isso a torna amigável à CI: os arquivos que você testou localmente são os arquivos que seu pipeline executa.

Como ambas as interfaces leem os mesmos arquivos .http, não há etapa de exportação separada. O que você commita é o que é executado.

O formato de arquivo .http

Um arquivo .http é uma lista de requisições separadas por ###. Cada requisição se parece quase com o HTTP bruto que ela envia. Aqui está um pequeno exemplo.

### Get a user
GET https://api.example.com/users/42
Accept: application/json

### Create a user
# @name createUser
POST https://api.example.com/users
Content-Type: application/json

{
  "name": "Ada Lovelace",
  "email": "ada@example.com"
}

### Use a value from the previous response
GET https://api.example.com/users/{{createUser.response.body.$.id}}
Authorization: Bearer {{token}}

Algumas coisas estão acontecendo aqui. As linhas ### separam as requisições. O comentário # @name nomeia uma requisição para que você possa referenciar sua resposta posteriormente. Os placeholders {{...}} puxam variáveis, incluindo valores encadeados de respostas anteriores. Este formato é compartilhado com a popular extensão REST Client, então os arquivos frequentemente se movem entre os dois com pequenas edições.

Variáveis e ambientes

httpYac lê variáveis de arquivos .env, de um arquivo http-client.env.json e de definições inline dentro do próprio arquivo de requisição. Você pode manter um conjunto de valores para o ambiente local, outro para o de staging e outro para o de produção, e então alternar entre eles sem editar a requisição.

@host = https://api.staging.example.com

### Login
# @name login
POST {{host}}/auth/login
Content-Type: application/json

{ "user": "{{USERNAME}}", "pass": "{{PASSWORD}}" }

Os segredos permanecem em arquivos .env que você mantém fora do Git, então o arquivo de requisição em si é seguro para ser commitado. Na CI, as mesmas variáveis vêm de variáveis de ambiente ou segredos do pipeline.

Scripting e asserções

É aqui que o httpYac vai além de um remetente de requisições básico. Você pode incorporar JavaScript em uma requisição para configurar dados antes que ela seja executada ou para verificar a resposta depois. Blocos de pré-requisição e pós-requisição são executados em um contexto Node, então você pode calcular uma assinatura, armazenar um token ou fazer asserções no corpo.

### Login and capture token
# @name login
POST {{host}}/auth/login
Content-Type: application/json

{ "user": "{{USERNAME}}", "pass": "{{PASSWORD}}" }

{{
  // post-request script
  test("status is 200", () => {
    client.assert.strictEqual(response.statusCode, 200);
  });
  exports.token = response.parsedBody.token;
}}

Esse token capturado fica então disponível para a próxima requisição como {{token}}. O modelo de scripting é flexível, o que faz parte do apelo para desenvolvedores que querem lógica sem precisar montar um framework de teste completo.

Executando httpYac na CI

A CLI é a ponte de "funciona na minha máquina" para "executa no pipeline". Instale-a e aponte-a para seus arquivos.

npm install -g httpyac

# Run a single file
httpyac send api/users.http

# Run every request in a folder, pick an environment, fail on assertion errors
httpyac send --all --env staging "api/**/*.http"

httpYac sai com um código diferente de zero quando uma asserção falha, que é o que um trabalho de CI precisa para marcar uma build como vermelha. Ele pode emitir saída no estilo JUnit para relatores de teste, então os resultados aparecem no seu painel de CI em vez de estarem enterrados nos logs. Insira esse comando no GitHub Actions, GitLab CI ou Jenkins e os mesmos arquivos que você editou no VS Code agora protegerão suas merges.

Quando usar httpYac

httpYac se encaixa em um formato específico de equipe e fluxo de trabalho. Opte por ele quando a maioria destas afirmações for verdadeira.

É menos adequado quando não-desenvolvedores precisam executar ou editar requisições, quando você quer uma visualização gráfica de grandes coleções de requisições, quando você precisa de ambientes compartilhados e sincronização de equipe sem configurar arquivos, ou quando você quer relatórios mais ricos e teste de carga em um só lugar. A ergonomia do texto simples é uma vantagem até que a suíte cresça e a equipe se expanda.

httpYac vs uma plataforma GUI e CI

httpYac é um executor de arquivos de texto. Apidog é um modelo diferente: uma plataforma de API que prioriza a GUI e que também é executada na CI. Nenhum é "melhor" em abstrato; eles resolvem o problema de pontas opostas. Seja claro em um ponto desde o início: Apidog não executa nem analisa nativamente arquivos .http. Se sua fonte da verdade é uma pasta de arquivos .http, o httpYac os executa diretamente, e essa é sua vantagem real.

Veja como os dois se comparam nos aspectos que geralmente decidem a escolha.

Se você deseja o lado visual, o Apidog permite que você construa e organize requisições sem escrever arquivos manualmente, e depois execute os mesmos cenários na CI com apidog run. A referência do comando apidog run detalha o comando, as flags de ambiente e os relatores. Você também obtém um servidor mock e documentação no mesmo workspace, algo que um executor de arquivos de texto deixa para outras ferramentas. Se mocking é uma necessidade real, nosso resumo de ferramentas de mocking de endpoint REST cobre as opções.

O resumo honesto: o httpYac vence quando todo o seu fluxo de trabalho é "arquivos no Git, execução no editor, reprodução na CI" e sua equipe é composta apenas por desenvolvedores. O Apidog vence quando você quer um workspace visual compartilhado, ambientes gerenciados, mocking e documentação junto com as execuções da CI. Algumas equipes até usam os dois, com o httpYac para verificações locais rápidas e o Apidog como a fonte da verdade da equipe. Escolha o modelo que melhor se adapta ao funcionamento da sua equipe.

Perguntas frequentes

O httpYac é gratuito?

Sim. httpYac é de código aberto sob a licença MIT. Tanto a extensão do VS Code quanto a CLI são gratuitas para instalar e usar. Não há nível pago ou requisito de conta para executar requisições localmente ou na CI.

Como o httpYac se difere da extensão REST Client?

Ambos usam o mesmo formato de arquivo .http, então os arquivos são em grande parte portáteis. httpYac adiciona uma CLI autônoma para execuções headless e na CI, um tratamento de ambiente mais amplo e um modelo de scripting e asserção mais rico. O REST Client é apenas para editor. Se você apenas envia requisições dentro do VS Code, qualquer um funciona; se você precisa executar os mesmos arquivos em um pipeline, a CLI do httpYac é o diferencial. Para uma visão mais ampla das ferramentas de editor, veja nossa lista de plugins do VS Code para teste de API.

O httpYac pode substituir o Postman?

Para um desenvolvedor que quer requisições em texto simples no Git e execuções na CI, o httpYac cobre muito do que as pessoas usam o Postman, menos a GUI, coleções compartilhadas e mocking integrado. Se sua equipe precisa de um workspace visual, ambientes gerenciados e mocking juntos, uma plataforma como o Apidog se alinha mais de perto. Compare as opções em nosso resumo de clientes de teste de API.

O httpYac suporta GraphQL e gRPC?

httpYac lida com requisições GraphQL e vários protocolos além do REST simples, incluindo alguns casos de streaming. Verifique a documentação oficial para a lista atual de protocolos, já que o suporte evolui entre os lançamentos. Para REST, o formato .http cobre os verbos, cabeçalhos, corpos e fluxos de autenticação comuns de forma nativa.

Conclusão

httpYac é uma resposta clara a uma necessidade clara: enviar requisições HTTP de arquivos de texto simples, executá-las no VS Code e reproduzi-las na CI sem uma etapa de exportação separada. Seu modelo nativo do Git, scripting e CLI gratuita o tornam uma forte escolha para equipes com muitos desenvolvedores que desejam que suas requisições vivam no repositório. A desvantagem é que tudo assume código, arquivos e fluência do desenvolvedor.

Se você preferir construir requisições visualmente, compartilhar ambientes gerenciados, simular endpoints e gerar documentos enquanto ainda executa testes na CI, o Apidog cobre essa área em um único workspace. Você pode baixar o Apidog e executar sua suíte com apidog run, ou manter o httpYac para verificações locais rápidas e deixar o Apidog ser a fonte da verdade da equipe. Escolha o modelo que melhor se adapta ao funcionamento da sua equipe.