Primeiramente, cURL é uma ferramenta free e open source utilizada para transferir dados por meio de requisições baseadas em URL. A sua principal utilização está voltada para requisições do tipo HTTP, entretanto, a ferramenta suporta também a FTP, IMAP, POP3, entre outros protocolos. 

Ainda discorrendo sobre a capacidade de cURL em trafegar dados, a ferramenta pode ser facilmente encontrada em aplicativos de softwares, equipamentos eletrônicos e dispositivos móveis, ou até mesmo em carros e utensílios domésticos. Por exemplo, a linguagem de programação .php faz uso de cURL para estabelecer conexão com endpoints. Já parou pra pensar que nesse exato momento sua smart TV esteja realizando requisições cURL para se conectar à aplicativos da web?

Sistemas operacionais são baseados em Linux ou MacOSX possuem cURL instalado nativamente, porém, quando estamos trabalhando em plataformas diferente das citadas, por exemplo na plataforma Windows, é necessário instalar previamente alguma ferramenta capaz de simular comandos Unix para ter acesso à cURL. Veja mais aqui, ou baixe o CygWin Open Source para começar a cURL.

Instalando cURL

Como já dito anteriormente, sistemas operacionais baseados em Linux já possuem cURL instalado nativamente. Já quando estamos trabalhando em plataforma Windows, é necessário instalar alguma ferramenta que simule comandos Unix. A tabela abaixo destaca qual ação tomar enquanto trabalhando nas quatro plataformas mais utilizadas em mercado.

Visando por maior clareza na explicação, além de manter um ambiente de testes uniforme com fácil acesso, estarei fazendo uso de curlonline para realizar as chamadas baseadas em cURL. Também faremos uso de JSON Place Holder que é um endpoint  que possui diversos dados mockados sem necessidade de autenticação. Ao longo deste post estarei detalhando mais ambas as ferramentas.

Encorajo também os leitores a fazerem uso das ferramentas citadas acima não somente para fins de estudo, mas sempre quando necessário pois a praticidade que fornecem podem reduzir o esforço de tempo consideravelmente. Por exemplo, é possível customizar facilmente diferentes opções nas request ao servidor através de um combo box. Dessa forma, a curva de aprendizado pode ser exponencial já que problemas de configurações e instabilidade de ambiente foram minimizados.

A vantagem de ter um serviço como este on cloud, é a possibilidade de acessá-lo de qualquer lugar, além disso, o site retorna as mensagens do servidor de uma maneira organizada.

Antes de continuar, é necessário entender qual formato de mensagem que cURL envia mensagens, ou seja, devemos entender qual o formato de mensagens HTTP assim como sua composição.

Formato de mensagens HTTP

Mensagens HTTP são aquelas que trafegam na web e que geralmente ocorrem nas interações entre client e server. Quando um usuário invoca uma página web pelo browser de seu computador, por sua vez, o browser requisita o conteúdo da página web (request) para o servidor e recebe uma mensagem de retorno com os dados da página no (response).

De acordo com a RFC 2616 – section 4 (Fielding, Roy), mensagens HTTP são dividas em duas partes: requests (client) e responses (server).

A composição de mensagens HTTP ( tanto request como response ) estão divididas da seguinte forma:

Start-Line

Linha de início obrigatória, sendo dividida entre duas partes:

• Request-Line: Indica a versão do HTTP. Exemplo HTTP/1.1
• Status-Line: Representa o HTTP statusCode de retorno. Por exemplo, no retorno HTTP/1.1 200 OK o status 200 indica que a mensagem foi processada com sucesso. Veja mais sobre em HTTP Status Codes

Header-Fields

Seção opcional, HTTP header permite que informações adicionais sejam trafegadas tanto nas requisições (request) como nos retornos (response). Essas informações adicionais podem ser desde da representação de um recurso solicitado (xml ou json) como a autenticação de um usuário em determinado serviço. 

Existe uma vasta lista de header-fields disponíveis, e a documentação pode ser encontrada em MDN.

Header-fields consistem em uma cadeia de chaves e valores, onde a chave encontra-se à esquerda e é case insensitive – uppercase e lowercase são indiferentes – e valores à direita e separados por ‘:’. Caso não seja especificado um nome para um header-field à esquerda, o valor a direita será ignorado.

Authentication : Basic UDZDMjRA==

Uma prática comum entre cURL e header fields pode ser descrita no exemplo abaixo, onde a autenticação e a representação do recursos /users/1 são definidos na seção header.

curl --header Authentication: null
     --header Content-Type: application/json
https://jsonplaceholder.typicode.com/users/1

Response Header:

HTTP/1.1 200 OK
Date: Fri, 16 Jun 2017 18:51:51 GMT
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Set-Cookie: __cfduid=d4759bf0ce12e18f33304884715a438c11497639111; expires=Sat, 16-Jun-18 18:51:51 GMT; path=/; domain=.typicode.com; HttpOnly
X-Powered-By: Express
Vary: Origin, Accept-Encoding
Access-Control-Allow-Credentials: true
Cache-Control: public, max-age=14400
Pragma: no-cache
Expires: Fri, 16 Jun 2017 22:51:51 GMT
X-Content-Type-Options: nosniff
Etag: W/"160d-1eMSsxeJRfnVLRBmYJSbCiJZ1qQ"
Via: 1.1 vegur
CF-Cache-Status: HIT
Server: cloudflare-nginx
CF-RAY: 36fff67f48d746ec-EWR

Response Body:

{
 "id": 1,
 "name": "Leanne Graham",
 "username": "Bret",
 "email": "Sincere@april.biz",
 "address": {
  "street": "Kulas Light",
  "suite": "Apt. 556",
  "city": "Gwenborough",
  "zipcode": "92998-3874",
  "geo": {
   "lat": "-37.3159",
   "lng": "81.1496"
   }
  },
 "phone": "1-770-736-8031 x56442",
 "website": "hildegard.org",
 "company": {
 "name": "Romaguera-Crona",
 "catchPhrase": "Multi-layered client-server neural-net",
 "bs": "harness real-time e-markets"
 }
}

Empty Line

Linha em branco obrigatória que divide o header e o body da mensagem. Praticamente, indica onde terminam os header-fields, e onde possivelmente começará o message-body.

Message-Body

Seção opcional que representa o corpo da mensagem, onde as mensagens legíveis são trafegadas. Em mensagens enviadas ao servidor (request), os dados da requisição são encontradas no corpo da mensagem, ou seja, no message-body. Nas mensagens de retorno (response) não é diferente, sendo o message-body responsável por trafegar as mensagens de retorno. No exemplo acima, a representação do recurso /users/1 se encontra na seção body.

Mãos à obra em cURL

Agora que já entendemos a estrutura de mensagens HTTP, vamos montar alguns exemplos de cURL. Primeira coisa, é entender como a estrutura do cURL, que será sempre a mesma, é composta. Se formos agora em linha de comando e executarmos o comando curl --help veremos que seu uso está restrito ao seguinte formato:

Usage: curl [options...] 

Onde [options…] é composto por uma vasta lista de opções disponibilizada pelo próprio comando curl --help, dividido por categorias. Por exemplo, a opção -i, -include solicita ao servidor que seja enviado o header e o body na mensagem de retorno.

curl -i https://jsonplaceholder.typicode.com/users

Vamos para alguns exemplos com cURL abaixo:

• Mensagem de retorno apenas com header

curl -I https://jsonplaceholder.typicode.com/users

• Mensagem de retorno apenas com body

curl https://jsonplaceholder.typicode.com/users

• Verbo GET, retorna apenas o body na representation JSON

curl -H "Accept: application/json" -X GET 
https://jsonplaceholder.typicode.com/users

• Verbo POST

curl -H "Content-Type: application/json" -X POST 
-d '{"name":"Arthur Silva","username":"silvaarthur"}' 
https://jsonplaceholder.typicode.com/users

• Verbo PATCH, atualização parcial de um recurso

curl -H "Content-Type: application/json" -X PATCH
-d '{"username":"undefined"}' 
https://jsonplaceholder.typicode.com/users/11

• Verbo DELETE

$ curl -X DELETE 
https://jsonplaceholder.typicode.com/users/10

• Verbo HEAD, similar à -i

$ curl -X HEAD
https://jsonplaceholder.typicode.com/users

Existem mais verbos e opções a serem usadas, e o que foi apresentado aqui é só uma parte daquilo o que cURL realmente é. Agora que terminou de ler esse post, vá até a linha de comando e digite aí aquele curl --help e mãos à obra!

Arthur Fuscella Silva (Linkedin)  – Fundador do blog ArrayOutOfIndex, é Bacharel em Ciências da Computação e trabalha com tecnologia de informação desde 2008. Acredita que inovações, transformação digital e novas ideias podem contribuir substancialmente para ambiente no qual vivemos, e consequentemente, a construir um futuro melhor pra todos nós.