Se você já tem uma API rodando, o curl permite testá-la diretamente pelo terminal. Com poucos comandos é possível fazer requisições GET, POST, PUT e DELETE, enviar JSON, adicionar cabeçalhos, conferir o código de status e identificar se um erro está no cliente, no endpoint ou no servidor.
http://localhost:3000. Se você ainda não criou essa API, use primeiro o tutorial API REST com Node.js e Express: CRUD na prática.1. Antes de testar: confirme se o curl está disponível
Abra o terminal, PowerShell ou Prompt de Comando e execute:
curl --version
Se o comando devolver a versão e os protocolos suportados, você já pode seguir. A documentação oficial define o curl como uma ferramenta de linha de comando para transferir dados de ou para servidores usando URLs, incluindo HTTP e HTTPS.
Neste tutorial, consideramos que a API está executando em:
http://localhost:3000
Abra outro terminal e mantenha o servidor da API rodando. Se estiver usando o projeto do artigo anterior, o comando é:
node server.js
2. GET: listar recursos
O método GET solicita uma representação atual do recurso. Para listar os produtos:
curl http://localhost:3000/produtos
Uma resposta possível é:
[
{"id":1,"nome":"Teclado","preco":120},
{"id":2,"nome":"Mouse","preco":80}
]
Para consultar apenas o produto de ID 1:
curl http://localhost:3000/produtos/1
-X GET. O curl já usa GET quando você informa somente a URL.3. Veja também os cabeçalhos da resposta
Quando o corpo da resposta não explica tudo, inclua -i. Isso mostra os cabeçalhos HTTP junto com o conteúdo:
curl -i http://localhost:3000/produtos/1
Você poderá ver uma primeira linha semelhante a:
HTTP/1.1 200 OK
Se consultar um ID inexistente, uma API bem configurada pode responder:
HTTP/1.1 404 Not Found
O status é parte importante do contrato. Não basta verificar apenas se algum JSON apareceu na tela.
4. POST: cadastrar um recurso enviando JSON
Para criar um produto, a API espera JSON. Em versões atuais do curl, a opção --json é uma forma simples de enviar o conteúdo com os cabeçalhos apropriados:
curl --json '{"nome":"Webcam","preco":250}' \
http://localhost:3000/produtos
A própria documentação do curl explica que --json funciona como um atalho para enviar os dados e acrescentar os cabeçalhos Content-Type: application/json e Accept: application/json. O curl não valida se o texto é um JSON correto; essa responsabilidade continua sendo sua.
Se preferir a forma mais explícita, útil para aprender o que está acontecendo:
curl -X POST http://localhost:3000/produtos \
-H "Content-Type: application/json" \
-d '{"nome":"Webcam","preco":250}'
Uma criação bem-sucedida normalmente devolve o recurso criado e um status 201 Created.
5. Entenda as opções usadas
| Opção | Função |
|---|---|
-X POST
|
Define explicitamente o método da requisição. |
-H
|
Adiciona um cabeçalho HTTP. |
-d
|
Envia dados no corpo da requisição. |
--json
|
Atalho para enviar JSON com cabeçalhos adequados. |
-i
|
Inclui os cabeçalhos da resposta na saída. |
-v
|
Mostra detalhes da comunicação para diagnóstico. |
6. PUT: atualizar um recurso existente
No projeto de exemplo, PUT substitui os campos editáveis do produto identificado pela URL. Para atualizar o produto 1:
curl -X PUT http://localhost:3000/produtos/1 \
-H "Content-Type: application/json" \
-d '{"nome":"Teclado mecânico","preco":220}'
Depois, confirme a alteração com outro GET:
curl http://localhost:3000/produtos/1
A RFC 9110 define PUT como a solicitação para criar ou substituir o estado do recurso-alvo com a representação enviada. Em APIs reais, PATCH também pode ser usado quando a intenção é alterar apenas parte do recurso.
7. DELETE: remover um recurso
Para excluir o produto 2:
curl -i -X DELETE http://localhost:3000/produtos/2
No projeto do Código em Sala, uma exclusão bem-sucedida responde com 204 No Content. Isso significa que a operação foi aceita e não existe corpo de resposta para exibir.
Confirme depois:
curl -i http://localhost:3000/produtos/2
Agora a resposta esperada é 404 Not Found.
8. Use o modo verboso quando algo der errado
A opção -v mostra informações de diagnóstico, incluindo a conexão, a linha da requisição, cabeçalhos enviados e cabeçalhos recebidos:
curl -v http://localhost:3000/produtos
Esse modo é especialmente útil para distinguir problemas diferentes: servidor fora do ar, URL errada, redirecionamento, autenticação ausente, cabeçalho incorreto ou resposta inesperada.
| Sintoma | O que verificar primeiro |
|---|---|
Failed to connect
|
Servidor parado, porta errada ou endereço incorreto. |
| 400 | JSON inválido, campo obrigatório ausente ou validação rejeitada. |
| 401 | Credencial de autenticação ausente ou inválida. |
| 403 | Cliente autenticado, mas sem permissão para a operação. |
| 404 | Endpoint ou recurso não encontrado. |
| 405 | Método reconhecido, mas não permitido naquele recurso. |
| 500 | Falha interna no servidor; consulte os logs da aplicação. |
9. Teste uma sequência completa de CRUD
Agora execute as operações na ordem para observar o ciclo completo:
# 1. Listar
curl http://localhost:3000/produtos
# 2. Criar
curl --json '{"nome":"Headset","preco":180}' \
http://localhost:3000/produtos
# 3. Consultar o novo recurso
curl http://localhost:3000/produtos/3
# 4. Atualizar
curl -X PUT http://localhost:3000/produtos/3 \
-H "Content-Type: application/json" \
-d '{"nome":"Headset USB","preco":210}'
# 5. Excluir
curl -i -X DELETE http://localhost:3000/produtos/3
# 6. Confirmar a exclusão
curl -i http://localhost:3000/produtos/3
Essa sequência transforma o CRUD em algo observável: cada comando produz uma requisição, cada endpoint executa uma regra e cada resposta informa o resultado.
10. Windows PowerShell: atenção ao comando curl
Em ambientes atuais do Windows, o executável curl.exe costuma estar disponível. Se seu terminal interpretar curl de outra forma ou houver conflito com aliases, tente escrever explicitamente:
curl.exe --version
Em comandos com JSON, as regras de aspas também mudam conforme o shell. Se uma linha copiada não funcionar no seu ambiente, confirme primeiro se o problema é o endpoint ou apenas a forma como o terminal interpretou as aspas.
11. Não coloque segredos em exemplos ou histórico do terminal
Ao testar APIs autenticadas, evite colar tokens reais em materiais públicos, capturas de tela ou repositórios. O histórico do shell também pode armazenar comandos. Para ambientes profissionais, prefira variáveis de ambiente, arquivos de configuração protegidos ou mecanismos próprios do cliente para lidar com credenciais.
Desafio prático
Com a API do artigo anterior, cadastre três produtos usando curl. Em seguida, atualize um deles, exclua outro e provoque de propósito uma resposta 400 e uma 404. Para cada operação, registre: método, URL, corpo enviado, código de status e corpo recebido.
Um teste útil possui objetivo e resultado esperado
Executar quatro comandos e receber resposta não demonstra que a API está correta. Para cada caso, defina estado inicial, requisição, status esperado, corpo esperado e estado final. Um teste de criação deve confirmar também que o recurso pode ser consultado depois.
| Caso | Requisição | Esperado |
|---|---|---|
| Produto válido | POST com nome e preço aceitos | 201, identificador e registro persistido |
| Campo obrigatório ausente | POST sem nome | 4xx e mensagem compreensível |
| ID inexistente | GET em recurso ausente | 404 sem dados falsos |
| JSON inválido | POST com corpo quebrado | 4xx; servidor continua funcionando |
Transforme a sequência em teste repetível
curl --fail-with-body \
--silent --show-error \
-H "Content-Type: application/json" \
-d '{"nome":"Caderno","preco":18.50}' \
http://localhost:3000/produtos--fail-with-body faz o comando sinalizar respostas HTTP de erro preservando o corpo para diagnóstico. Não coloque tokens diretamente em scripts versionados; use ambiente de teste e variáveis protegidas.
Matriz de oito testes
Crie dois casos para cada método: um de sucesso e um de falha. Registre comando, status, trecho relevante do corpo e verificação posterior. Execute novamente em outra ordem para descobrir testes que dependem acidentalmente de dados anteriores.
Perguntas frequentes
curl serve apenas para APIs REST?
Não. O curl suporta vários protocolos e pode ser usado em muitos tipos de transferência. Neste artigo estamos usando HTTP para testar uma API.
Preciso usar -X GET?
Normalmente não. Ao fornecer apenas uma URL HTTP, o curl faz GET por padrão. Use opções adicionais quando precisar alterar o comportamento da requisição.
Postman e curl fazem a mesma coisa?
Ambos podem atuar como clientes HTTP. O Postman oferece interface gráfica e recursos de coleção; o curl é leve, funciona muito bem no terminal e é fácil de incorporar em scripts.
Um status 200 significa que a API está correta?
Não necessariamente. Você também precisa conferir se o corpo, os cabeçalhos e os efeitos da operação correspondem ao contrato esperado.
Conclusão
Testar uma API com curl aproxima você do funcionamento real do HTTP. Em vez de clicar em botões, você controla método, URL, cabeçalhos e corpo e observa exatamente o que o servidor devolve. Depois que GET, POST, PUT e DELETE ficam claros no terminal, ferramentas gráficas deixam de ser uma caixa-preta e passam a ser apenas outra forma de montar as mesmas requisições.
Referências bibliográficas
- BROWN, Ethan. Web Development with Node and Express . 2. ed. O’Reilly Media, 2019.
- RICHARDSON, Leonard; AMUNDSEN, Mike; RUBY, Sam. RESTful Web APIs . 1. ed. O’Reilly Media, 2013.
Documentação técnica: curl, curl man page e everything curl — JSON. Norma técnica: IETF, RFC 9110 — HTTP Semantics, 2022.