Como usar o Carom

#Sua primeira requisição

Dez segundos entre abrir o app e ter uma resposta.

1. Aperte CtrlN para uma nova requisição — ou use o + na faixa de abas.
2. Escolha o método e digite a URL. {{baseUrl}}/pokemon/pikachu funciona depois que você definir baseUrl (veja Variáveis).
3. Aperte CtrlEnter — ou Enter com o cursor no campo da URL — para enviar.
4. A resposta aparece à direita: status, tempo, tamanho e o corpo formatado.

#Workspaces, pastas e abas

Um workspace reúne pastas, requisições e ambientes. Alterne entre eles com CtrlR ou pelo menu no topo da barra lateral.

• As pastas agrupam requisições, podem ser aninhadas e podem ter suas próprias variáveis, autenticação e scripts, que valem para tudo dentro delas.
• Arraste e solte para reordenar ou mover uma requisição para uma pasta. Arrastar fica desligado enquanto há um filtro ativo, para nada cair no lugar errado.
• Filtre a árvore na caixa acima dela, ou vá direto a uma requisição com CtrlP.
• Clique com o botão direito numa aba para localizá-la na árvore, fechá-la, fechar as outras ou fechar todas. CtrlW fecha a aba ativa; CtrlShiftE busca entre as abertas.
• CtrlB esconde e mostra a barra lateral.

#Montando uma requisição

Cada requisição tem um conjunto de abas abaixo da barra da URL:

Defina a autenticação uma vez numa pasta e toda requisição dentro dela a herda; uma requisição ainda pode escolher a sua.

#Variáveis e ambientes

Escreva {{nome}} em qualquer lugar — URL, cabeçalhos, corpo, autenticação — e o Carom preenche na hora de enviar.

De onde vem um valor

1. A pasta em que a requisição está. Com pastas aninhadas, vence a mais interna.
2. O ambiente ativo, escolhido no seletor no canto superior direito.
3. O ambiente base, compartilhado por todos os outros.

Passe o mouse numa variável para ver o valor e qual dos três a forneceu. Uma variável que não está definida em lugar nenhum aparece em vermelho.

Definir e alterar

• Passe o mouse numa variável, na URL ou dentro de um corpo, e edite ali mesmo — ou defina, se ela ainda não existir.
• Selecione qualquer texto, clique com o botão direito e escolha Definir uma variável existente ou Nova variável…. O valor vai para o ambiente selecionado, e o que você selecionou é trocado pela referência.
• CtrlE abre a gaveta de ambientes, um editor rápido ao lado da requisição que mostra o ambiente ativo e as variáveis da pasta. Gerenciar ambientes, no seletor, abre o diálogo completo para adicionar, renomear, colorir, copiar entre eles e excluir ambientes.

#Dados gerados

Variáveis inventadas na hora de enviar. Úteis para fixtures, formulários e volumes de dados com cara de verdade.

Escreva uma entre chaves — {{$randomEmail}} — e ela vira um valor novo a cada envio. Cada ocorrência recebe o seu próprio valor, então dois {{$randomFullName}} no mesmo corpo são duas pessoas diferentes. É isso que separa um gerador de uma variável.

• Os nomes são os do Postman, então uma coleção que os usava continua funcionando.
• Nomes, cidades, ruas e telefones seguem o idioma da interface. Identificadores, números e datas não têm idioma e nunca mudam.
• Para fixar o idioma de forma independente — uma API que valida endereços em inglês, lida por quem trabalha em português — defina Dados gerados em Configurações → Geral.
• Uma variável que você define com o mesmo nome vence o gerador.
• Um gerador com erro de digitação continua vermelho, que é o caso que vale notar.

Nada corresponde a isso.

#Scripts

JavaScript que roda antes de uma requisição ser enviada ou depois que a resposta chega.

Coloque um script numa requisição ou numa pasta. Os scripts de uma pasta envolvem cada requisição dentro dela: os de pré-requisição rodam da pasta mais externa para dentro, os de pós-resposta da mais interna para fora.

// Script de pós-resposta: guarda o token para a próxima requisição
const body = carom.json();
if (body && body.token) carom.set("token", body.token);

O objeto pm do Postman também funciona, pm.test inclusive, então scripts de uma coleção importada rodam sem alteração.

#Lendo uma resposta

• Formatado recolhe e expande o JSON; Bruto é exatamente o que voltou; Prévia renderiza HTML.
• Destacar no corpo encontra um texto e marca todas as ocorrências.
• Cabeçalhos, Cookies e Console (saída dos scripts e resultados de pm.test) têm abas próprias.
• Histórico guarda as últimas 15 respostas de cada requisição. Clique numa para vê-la de novo.
• Copie a resposta, ou salve em arquivo, pelos botões acima do corpo.
• Quando chega uma resposta de uma requisição em outra aba, um aviso conta para você.

Para passar uma requisição a alguém como comando, use Copiar como curl ao lado da barra da URL. Ele sai com as suas variáveis já preenchidas — e com os valores gerados, se o corpo tiver. Copiar URL entrega a URL resolvida.

#Importar e exportar

Importar

Use Importar no fim da barra lateral. O Carom lê exportações do Carom, coleções e ambientes do Postman, Insomnia v4 e v5, OpenAPI / Swagger, arquivos HAR e comandos curl colados. No Postman você escolhe o que trazer e para onde vai, ambientes inclusive. O que não vem junto — uma requisição gRPC do Insomnia, por exemplo — aparece listado antes de você confirmar.

Exportar

Use Exportar para um workspace, uma pasta (com suas subpastas e requisições) ou uma única requisição, no formato do Carom ou em OpenAPI 3.1. Escolha o recorte — ambientes inclusive — e onde salvar.

#Compartilhando um workspace com o time

Só no app desktop.

No menu do workspace escolha Guardar este workspace numa pasta e indique uma pasta do seu projeto. Uma pasta vazia recebe o workspace como ele está; uma pasta que já tem um substitui o workspace pelo que está nela.

• Uma requisição por arquivo: duas pessoas que adicionam requisições diferentes mudam arquivos diferentes, e o git junta sem perguntar.
• Pastas, requisições e ambientes vão para a pasta. Respostas, edições não salvas e versões salvas ficam na sua máquina.
• Os nomes das variáveis sempre viajam. Os valores só viajam onde você mandar — a tela seguinte pergunta, e tudo o que parece credencial começa desligado.
• As mudanças são gravadas um instante depois que você para de digitar, e só nos arquivos que mudaram.
• Se a pasta mudar por baixo — depois de um git pull com o app aberto — o Carom para de gravar e avisa. Recarregue do disco e siga em frente.

#Atalhos de teclado

Os padrões. Todos podem ser alterados em Configurações → Geral → Atalhos de teclado.

Nos editores de código

#Temas, cores e idioma

• Configurações → Geral: o idioma da interface (English, Português, Español — segue o sistema até você escolher), o idioma dos dados gerados, layout dos painéis, tempo limite, redirecionamentos, se o app desktop pede respostas comprimidas aos servidores e Atalhos de teclado.
• Configurações → Tema: escuro ou claro, cinco paletas prontas (Carom, Midnight, Ember, Forest, Paper) e fontes com tamanho. Mude qualquer cor de uma paleta pronta e ela vira uma cópia sua; Me surpreenda sorteia uma nova.
• No desktop, Configurações → Geral → Atualizações verifica se há versão nova e deixa você escolher se o Carom verifica sozinho ao iniciar.

#Quando algo não está certo

Achou outra coisa? Abra uma issue contando o que fez, o que esperava e o que aconteceu.