Teste uma API REST com curl

1. Visão geral

Este tutorial oferece uma breve visão geral do teste de uma API REST usandocurl.

curl is a command-line tool for transferring data and supports about 22 protocols including HTTP. Essa combinação o torna uma ferramenta ad-hoc muito boa para testar nossos serviços REST.

Leitura adicional:

Testando APIs da Web com coleções de carteiro

Aprenda a criar uma coleção de carteiro que pode testar uma API REST

Um Guia para Garantia de REST

Explore os conceitos básicos da REST-assegurada - uma biblioteca que simplifica o teste e a validação das APIs REST.

2. Opções de linha de comando

curl supports over 200 command-line options. E podemos ter zero ou mais deles para acompanhar a URL no comando.

Mas antes de usá-lo para nossos propósitos, vamos dar uma olhada em dois que tornariam nossas vidas mais fáceis.

2.1. Verbose

Quando estamos testando, é uma boa ideia ativar o modo detalhado:

curl -v http://www.example.com/

Como resultado, os comandos forneceriam informações úteis, como o endereço IP resolvido, a porta à qual estamos tentando conectar e os cabeçalhos.

2.2. Resultado

Por padrão, curl gera o corpo da resposta na saída padrão. Opcionalmente, podemos fornecer a opção de saída para salvar em um arquivo:

curl -o out.json http://www.example.com/index.html

Isso é especialmente útil quando o tamanho da resposta é grande.

3. Métodos HTTP com curl

Toda solicitação HTTP contém um método. Os métodos mais usados são GET, POST, PUT e DELETE.

3.1. GET

Este é o método padrão ao fazer chamadas HTTP com curl. De fato, os exemplos mostrados anteriormente eram chamadas GET simples.

Ao executar uma instância local de um serviço na porta 8082, usaríamos algo como este comando para fazer uma chamada GET:

curl -v http://localhost:8082/spring-rest/foos/9

E como temos o modo verbose ativado, obteríamos um pouco mais de informações junto com o corpo da resposta:

*   Trying ::1...
* TCP_NODELAY set
* Connected to localhost (::1) port 8082 (#0)
> GET /spring-rest/foos/9 HTTP/1.1
> Host: localhost:8082
> User-Agent: curl/7.60.0
> Accept: */*
>
< HTTP/1.1 200
< X-Application-Context: application:8082
< Content-Type: application/json;charset=UTF-8
< Transfer-Encoding: chunked
< Date: Sun, 15 Jul 2018 11:55:26 GMT
<
{
  "id" : 9,
  "name" : "TuwJ"
}* Connection #0 to host localhost left intact

3.2. POST

Usamos esse método para enviar dados para um serviço de recebimento. E para isso, usamos a opção de dados.

A maneira mais simples de fazer isso é incorporar os dados no comando:

curl -d 'id=9&name=example' http://localhost:8082/spring-rest/foos/new

ou, passe um arquivo contendo o corpo da solicitação para a opção de dados como esta:

curl -d @request.json -H "Content-Type: application/json"
  http://localhost:8082/spring-rest/foos/new

Usando os comandos acima como estão, podemos receber mensagens de erro como a seguinte:

{
  "timestamp" : "15-07-2018 05:57",
  "status" : 415,
  "error" : "Unsupported Media Type",
  "exception" : "org.springframework.web.HttpMediaTypeNotSupportedException",
  "message" : "Content type 'application/x-www-form-urlencoded;charset=UTF-8' not supported",
  "path" : "/spring-rest/foos/new"
}

Isso ocorre porque o curl adiciona o seguinte cabeçalho padrão a todas as solicitações POST:

Content-Type: application/x-www-form-urlencoded

Isso também é o que os navegadores usam em um POST simples. Em nosso uso, geralmente queremos personalizar os cabeçalhos de acordo com nossas necessidades.

Por exemplo, se nosso serviço espera o tipo de conteúdo json, podemos usar a opção -H para modificar nossa solicitação POST original:

curl -d '{"id":9,"name":"example"}' -H 'Content-Type: application/json'
  http://localhost:8082/spring-rest/foos/new

O prompt de comando do Windows não oferece suporte para aspas simples, como os shells semelhantes ao Unix.

Como resultado, precisaríamos substituir as aspas simples por aspas duplas; escapando deles sempre que necessário:

curl -d "{\"id\":9,\"name\":\"example\"}" -H "Content-Type: application/json"
  http://localhost:8082/spring-rest/foos/new

Além disso, quando queremos enviar uma quantidade um pouco maior de dados, geralmente é uma boa ideia usar um arquivo de dados.

3.3. PUT

Este método é muito semelhante ao POST. Mas nós o usamos quando queremos enviar uma nova versão de um recurso existente. Para fazer isso, usamos a opção -X.

Sem nenhuma menção a um tipo de método de solicitação, o padrão de ondulação é usar GET. Portanto, mencionamos explicitamente o tipo de método no caso de PUT:

curl -d @request.json -H 'Content-Type: application/json'
  -X PUT http://localhost:8082/spring-rest/foos/9

3.4. EXCLUIR

Novamente, especificamos que queremos usar DELETE usando a opção -X:

curl -X DELETE http://localhost:8082/spring-rest/foos/9

4. Cabeçalhos personalizados

Podemos substituir os cabeçalhos padrão ou adicionar nossos próprios cabeçalhos.

Por exemplo, para alterar o cabeçalho do host, fazemos o seguinte:

curl -H "Host: com.example" http://example.com/

Para desativar o cabeçalho User-Agent, colocamos um valor vazio:

curl -H "User-Agent:" http://example.com/

O cenário mais comum durante o teste é alterar o cabeçalho Content-Type e Accept. Teríamos apenas que prefixar cada cabeçalho com a opção -H:

curl -d @request.json -H "Content-Type: application/json"
  -H "Accept: application/json" http://localhost:8082/spring-rest/foos/new

5. Autenticação

Umservice that requires authentication enviaria de volta um 401 - código de resposta HTTP não autorizado e um cabeçalho WWW-Authenticate associado.

Para autenticação básica, podemossimply embed the username and password combination inside our request using the user option:

curl --user example:secretPassword http://example.com/

No entanto, se quisermosuse OAuth2 for authentication, primeiro precisaremos obter o access_token de nosso serviço de autorização.

A resposta do serviço conteria oaccess_token:

{
  "access_token": "b1094abc0-54a4-3eab-7213-877142c33fh3",
  "token_type": "bearer",
  "refresh_token": "253begef-868c-5d48-92e8-448c2ec4bd91",
  "expires_in": 31234
}

Agora, podemos usar o token em nosso cabeçalho de autorização:

curl -H "Authorization: Bearer b1094abc0-54a4-3eab-7213-877142c33fh3" http://example.com/

6. Conclusão

Examinamos o uso da funcionalidade mínima de curl para testar nossos serviços REST. Embora possa fazer muito mais do que o que foi discutido aqui, para nosso propósito, isso deve bastar.

Sinta-se à vontade para digitar curl -h na linha de comando para verificar todas as opções disponíveis. O serviço REST usado para a demonstração está disponívelhere on GitHub.

TOC

Teste uma API REST com curl