No VSCode existe uma extensão chamada "Rest Client", que permite escrever e enviar requests com um clique, apartir de um arquivo como esse:

POST http://localhost:8080/create-user
Content-Type application/json

{
  "name": "UserName",
  "email": "[email protected]"
  "password": "password"
}
###

Eu acho essa extensão bem interessante, mas ao mesmo tempo, ter q alterar o payload diretamente no arquivo pra cada usuario que voce quiser testar, é um tanto redundante.

Para resolver esse dilema, eu criei um CLI em bash, usando meu próprio gerenciador de pacotes (também feito em bash), que torna isso bem mais modular.

A ideia é semelhante à extensão, você cria um arquivo com o nome cry.sh, e dedntro dele define as suas requests:

host http://localhost:8080 # define o base-url para as requests

begin create-user
  post /create-user
  json-body '{
    <mesmo json de antes>
  }'
end

Com isso, agente pode fazer o mesmo que a extensão, porem, ao invez de clicar numa interface, agente pode executar a request com cry create-user no terminal.

Até ai, não tem grande vantagem. Mais o cry possui um mecanismo de required fields, que permite definir campos variaveis:

host http://localhost:8080 # define o base-url para as requests

begin create-user
  require name email password # campos necessarios
  post /create-user
  json-body '{
    "name": "%name", 
    "email": "%email",
    "password": "%password"
  }'
end

Usando os required fields no lugar dos valores hardcoded, o cry irá perguntar por quais valores usar na proxima vez que você executar o comando create-user:

$ cry create-user
Enter value for 'name': NewUser
Enter value for 'email': [email protected]
Enter value for 'password': 12345678

Mas e se durante o desenvolvimento você precisar criar o mesmo usuario varias vezes, ou se quiser testar algum outro tipo de request que possua varias opções? Seria meio chato escrever a mesma coisa toda hora.

Para isso, o cry possui uma função use-template, que basicamente copia todas as configuracoes de um determinado commando:

...

begin create-root
  use-template create-user # Herda o create-user
  
  # Definindo os campos requiridos:
  name="Root"
  email="[email protected]"
  password="root1234"
end

Com isso, ao chamar cry create-root, ele não vai nem perguntar nada, apenas executar a request como se os valores já estivessem lá.

OBS: Aquelas variaveis definidas dentro do commando create-root estão no contexto global do bash, o que podeia causar problema para outros commandos, mas a função end deleta essas variaveis (name, email e password) do contexto global, então não haverá conflito.

E como isso funciona?

O cry nada mais é do que uma abstração do curl, tudo que ele faz é organizar os dados, gerar um commando curl, e executar.

Se voce usar -e antes do nome de um comando ele mostra o comando ao invez de fazer a request:
cry -e create-root

Uma observacão importante: O arquivo cry.sh é usado pelo cry para gerar um cache dos comandos, e tudo que ele faaz é salvo dedntro de uma pasta oculta, junto ao script (em .cry). Isso signfica que, esse arquivo só é executado quando o cry detecta alguma alteracão, portanto, usar variaveis de ambiente (no estilo shell) pode causar problemas.

Caso seja necessario usar variaveis de ambiente, podemos usar a função use-env:

use-env PORT 8080 # Define 8080 com default caso não definida

host http://localhost:%PORT # semelhante aos require fields

A diferença disso para um required field é que o valor será pego do embiente do shell e não terá um dialogo perguntando o valor.

Cookies

O cry também tem um suporte interessante para cookies.

Vamos supor que a nossa api retorne um token de acesso jtw quando a request para /create-user é bem sucedida. Da forma que fizemos o comando create-user anteriormente, ele iria apenas printar o token no console. Mas, o cry possui uma função que permite armazenar os cookies:

begin create-user
  ...
  use-cookies cookie-name
end

Dessa forma, quando chamarmos o comando para criar um usuario, (ou mesmo o create-root, já que o usa ele usa como template), os cookies seram armazenados, num arquivo com o nome escolhido (cookie-name).

Isso significa que, se quisermos fazer uma request que precise de permisão, agente pode usar esse mesmo cookie com exatamente o mesmo comando use-cookies cookie-name.

OBS: Os arquivos de cookies ficam em .cry/cookies/

Isso ainda não está usando todo o potêncial do cry!

Como eu disse, o nome passado para o use-cookies é usado como o nome do arquivo onde ele será salvo, o que sigfica que, para varios usuarios, essa estrategia não funcionaria, sempre que usarmos o create-user, os cookies serão sobrescritos.

Para resolver isso é simples, pasta usarmos os required fields:

begin create-user
  ...
  use-cookies %name # Um cookie para cada usuario!
end

Assim, basta passar um campo name como required field em cada comando que dependa dos tokens de acesso, e tudo deve funcionar como o esperado!

Como instalar

Bem, como eu disse no começo, o cry usa um gerenciador de pacotes que eu mesmo criei, o bpm. Para instalar o bpm é tão simples quanto executar um unico script, e após instaldo, é ainda mais facil de instalar o cry:

$ bpm install cry
$ bpm export cry

OBS: Sem exportar, o cry não fica disponível no contexto global, e seria necessario usar bpm run cry ao invez de so escrever cry.

Ok, por hoje é só. Caso queiram ver o projeto, ele está no meu github