Що JS-розробнику варто знати про Curl

Curl — популярний інструмент командного рядка для здійснення HTTP-запитів, він універсальний та підтримує широкий набір протоколів. Але зараз ми зосередимось на протоколі HTTP, адже розглянемо Curl саме з погляду JavaScript-розробника.

Якщо ви звернетесь до документації Curl, доведеться перебрати 383 прапори, аби знайти потрібну комбінацію для вашої задачі. У цій статті ми поговоримо про поширені шаблони використання Curl, аби спростити виконання запитів у командному рядку. Для запитів з прикладів використаємо сервіс httpbin.org.

Запит HTTP GET

Насамперед перевірте, чи встановлений у вас curl, для цього виконайте: curl --version.

$ curl --version
curl 7.58.0 (x86_64-pc-linux-gnu) libcurl/7.58.0 OpenSSL/1.1.1 zlib/1.2.11 libidn2/2.0.4 libpsl/0.19.1 (+libidn2/2.0.4) nghttp2/1.30.0 librtmp/2.3
Release-Date: 2018-01-24
Protocols: dict file ftp ftps gopher http https imap imaps ldap ldaps pop3 pop3s rtmp rtsp smb smbs smtp smtps telnet tftp 
Features: AsynchDNS IDN IPv6 Largefile GSS-API Kerberos SPNEGO NTLM NTLM_WB SSL libz TLS-SRP HTTP2 UnixSockets HTTPS-proxy PSL 

Аби надіслати запит HTTP GET, просто виконайте команду curl <url>. Наприклад, для get-запиту на https://httpbin.org/get?answer=42, виконайте curl https://httpbin.org/get?answer=42:

$ curl https://httpbin.org/get?answer=42
{
  "args": {
    "answer": "42"
  }, 
  "headers": {
    "Accept": "*/*", 
    "Host": "httpbin.org", 
    "User-Agent": "curl/7.58.0", 
    "X-Amzn-Trace-Id": "Root=1-5ee8d737-b39c6a466892725bbb52b916"
  }, 
  "origin": "69.84.111.39", 
  "url": "https://httpbin.org/get?answer=42"
}

Якщо запит виконався успішно, curl виводить тіло HTTP-відповіді. Аби curl вивів повну відповідь, включно із заголовками запиту, використайте прапор -i.

$ curl -i https://httpbin.org/get?answer=42
HTTP/2 200 
date: Tue, 16 Jun 2020 14:30:57 GMT
content-type: application/json
content-length: 801
server: istio-envoy
access-control-allow-origin: *
access-control-allow-credentials: true
x-envoy-upstream-service-time: 2

{
  "args": {
    "answer": "42"
  }, 
  "headers": {
    "Accept": "*/*", 
    "Content-Length": "0", 
    "Host": "httpbin.org", 
    "User-Agent": "curl/7.58.0", 
    "X-Amzn-Trace-Id": "Root=1-5ee8d7a1-cb3954c09299eb9e0dff70a6", 
    "X-B3-Parentspanid": "dffc55451e64b5fc", 
    "X-B3-Sampled": "0", 
    "X-B3-Spanid": "8e233a863fb18b6c", 
    "X-B3-Traceid": "45bd12a9067fb5c0dffc55451e64b5fc", 
    "X-Envoy-External-Address": "10.100.91.201", 
    "X-Forwarded-Client-Cert": "By=spiffe://cluster.local/ns/httpbin-istio/sa/httpbin;Hash=c1ff14671b3e24ee794f9a486570abf8ccc9d622846611d3f91a322db4d480cd;Subject=\\"\\";URI=spiffe://cluster.local/ns/istio-system/sa/istio-ingressgateway-service-account"
  }, 
  "origin": "69.84.111.39,10.100.91.201", 
  "url": "http://httpbin.org/get?answer=42"
}

Результат вище — неформатована HTTP-відповідь. Рядки заголовків починаються з поля date:, а закінчуються x-envoy-upstream-service-time:.

Завантаження файлу

Для завантаження файлів через інтерфейс командного рядка часто використовується Wget. Більшість дистрибутивів Linux вже з коробки підтримують його, а от OSX — ні.

Насправді ж команда wget url має свій еквівалент в curl — curl -OL url. Опція -O вказує curl зберегти тіло відповіді в локальному файлі. А от параметр -L вказує слідувати перенаправленням.

Спробуймо завантажити зображення з Unsplash, розташоване за посиланням: https://images.unsplash.com/photo-1506812574058-fc75fa93fead. Виконаємо таку команду:

$ curl -OL https://images.unsplash.com/photo-1506812574058-fc75fa93fead
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100 12.1M  100 12.1M    0     0  3927k      0  0:00:03  0:00:03 --:--:-- 3927k
$

Параметр -O потрібен, аби призначити файлу назву, яка відповідатиме частині URl після /. Тож в нашому прикладі зображення буде збережено в поточній директорії з назвою файлу photo-1506812574058-fc75fa93fead. Аби налаштувати іншу назву для файлу, використайте прапор -o:

$ curl -o miami-beach.jpg https://images.unsplash.com/photo-1506812574058-fc75fa93fead
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100 12.1M  100 12.1M    0     0  6083k      0  0:00:02  0:00:02 --:--:-- 6083k
$ ls -l miami-beach-jpg
-rw-rw-r-- 1 val val 12788445 Jun 16 11:03 miami-beach.jpg
$

Запити з авторизацією

Заголовок авторизації зберігає дані для отримання доступу до захищених ресурсів у RESTful API. Аби вручну налаштувати заголовки авторизації, використайте прапор -H, який відповідає за налаштування заголовків запиту. Наприклад, якщо ваш API ключ — my-secret-token, ви можете додати його до URL з авторизацією так:

$ curl -H "Authorization: my-secret-token" https://httpbin.org/get
{
  "args": {}, 
  "headers": {
    "Accept": "*/*", 
    "Authorization": "my-secret-token", 
    "Host": "httpbin.org", 
    "User-Agent": "curl/7.58.0", 
    "X-Amzn-Trace-Id": "Root=1-5ee8e1a5-a3aa30e0765a7980b04ca4a0"
  }, 
  "origin": "69.84.111.39", 
  "url": "https://httpbin.org/get"
}
$

Зверніть увагу, що httpbin.org/get передає назад заголовки HTTP-запиту в тілі відповіді (властивість headers).

Curl також підтримує базову автентифікацію з прапором -u. Спробуймо надіслати запит з даними про ім'я користувача user і пароль pass:

$ curl -i -u "user:pass" https://httpbin.org/basic-auth/user/pass
HTTP/2 200 
date: Tue, 16 Jun 2020 15:18:45 GMT
content-type: application/json
content-length: 47
server: istio-envoy
access-control-allow-origin: *
access-control-allow-credentials: true
x-envoy-upstream-service-time: 1

{
  "authenticated": true, 
  "user": "user"
}
$

Якщо ж дані для автентифікації виявляться хибними:

$ curl -i -u "user:wrongpass" https://httpbin.org/basic-auth/user/pass
HTTP/2 401 
date: Tue, 16 Jun 2020 15:18:51 GMT
content-length: 0
server: istio-envoy
www-authenticate: Basic realm="Fake Realm"
access-control-allow-origin: *
access-control-allow-credentials: true
x-envoy-upstream-service-time: 12

$

POST-запит з JSON

Якщо в curl вам потрібні не лише GET, а й інші HTTP-методи, використовуйте прапор -X, аби задати потрібний метод. Автоматично curl надсилає GET-запити, тому явно цей метод не вказується (curl -X GET).

Прапор -X часто використовується у комбінації з -d для визначення тіла запиту. Для прикладу, відправимо POST-запит з деякими JSON-даними:

$ curl -X POST -d '{"answer":42}' https://httpbin.org/post
{
  "args": {}, 
  "data": "", 
  "files": {}, 
  "form": {
    "{\\"answer\\":42}": ""
  }, 
  "headers": {
    "Accept": "*/*", 
    "Content-Length": "13", 
    "Content-Type": "application/x-www-form-urlencoded", 
    "Host": "httpbin.org", 
    "User-Agent": "curl/7.58.0", 
    "X-Amzn-Trace-Id": "Root=1-5ee8e3fd-8437029087be44707bd15320", 
    "X-B3-Parentspanid": "2a739cfc42d28236", 
    "X-B3-Sampled": "0", 
    "X-B3-Spanid": "8bdf030613bb9c8d", 
    "X-B3-Traceid": "75d84f317abad5232a739cfc42d28236", 
    "X-Envoy-External-Address": "10.100.91.201", 
    "X-Forwarded-Client-Cert": "By=spiffe://cluster.local/ns/httpbin-istio/sa/httpbin;Hash=ea8c3d70befa0d73aa0f07fdb74ec4700d42a72889a04630741193548f1a7ae1;Subject=\\"\\";URI=spiffe://cluster.local/ns/istio-system/sa/istio-ingressgateway-service-account"
  }, 
  "json": null, 
  "origin": "69.84.111.39,10.100.91.201", 
  "url": "http://httpbin.org/post"
}
$ 

Зверніть увагу, що автоматично curl встановлює значення заголовку Content-Type як application/x-www-form-urlencoded. Для JSON потрібні інші налаштування Content-Type. Аби змінити заголовок запиту, використаємо вже відомий нам прапор -H:

$ curl -X POST -d '{"answer":42}' -H "Content-Type: application/json" https://httpbin.org/post
{
  "args": {}, 
  "data": "{\\"answer\\":42}", 
  "files": {}, 
  "form": {}, 
  "headers": {
    "Accept": "*/*", 
    "Content-Length": "13", 
    "Content-Type": "application/json", 
    "Host": "httpbin.org", 
    "User-Agent": "curl/7.58.0", 
    "X-Amzn-Trace-Id": "Root=1-5ee8e45e-ad875af4f83efd4379b86c34", 
    "X-B3-Parentspanid": "5f4f33d1c5ea13aa", 
    "X-B3-Sampled": "0", 
    "X-B3-Spanid": "a062c9bf2ebfd4bd", 
    "X-B3-Traceid": "44aa8d62412ae34d5f4f33d1c5ea13aa", 
    "X-Envoy-External-Address": "10.100.86.47", 
    "X-Forwarded-Client-Cert": "By=spiffe://cluster.local/ns/httpbin-istio/sa/httpbin;Hash=2f0b3331fe4d512975b4b82583a55dd5d1196023d0dfce9e0abed246991c5b67;Subject=\\"\\";URI=spiffe://cluster.local/ns/istio-system/sa/istio-ingressgateway-service-account"
  }, 
  "json": {
    "answer": 42
  }, 
  "origin": "69.84.111.39,10.100.86.47", 
  "url": "http://httpbin.org/post"
}

PUT-запит з JSON

Прапор -d зручний для невеликих запитів, але це не варіант, якщо вам треба відправити великі обсяги JSON-даних. У таких випадках дані зручніше розмістити в локальному файлі й оперувати ним.

Припустимо, файл data.json містить такі дані:

{"answer":42}

Аби здійснити запит HTTP PUT з даними файлу, використовуємо той самий прапор -d, але тепер передамо йому як значення назву файлу '@data.json', а не безпосередньо рядок даних. Префікс @ вказує curl завантажити тіло запиту з відповідного файлу:

$ curl -X PUT -d '@data.json' -H "Content-Type: application/json" https://httpbin.org/put
{
  "args": {}, 
  "data": "{\\"answer\\":42}", 
  "files": {}, 
  "form": {}, 
  "headers": {
    "Accept": "*/*", 
    "Content-Length": "13", 
    "Content-Type": "application/json", 
    "Host": "httpbin.org", 
    "User-Agent": "curl/7.58.0", 
    "X-Amzn-Trace-Id": "Root=1-5ee8e745-37c4ef06326b7b4354a16b94", 
    "X-B3-Parentspanid": "a4f8f91f4f1b051e", 
    "X-B3-Sampled": "0", 
    "X-B3-Spanid": "a018b1a3fcebdc68", 
    "X-B3-Traceid": "7b48b01dc3f632eea4f8f91f4f1b051e", 
    "X-Envoy-External-Address": "10.100.91.201", 
    "X-Forwarded-Client-Cert": "By=spiffe://cluster.local/ns/httpbin-istio/sa/httpbin;Hash=6035260d9d551af6c1907270653214e8d3195abbdd19078c1c84fd9a4106f260;Subject=\\"\\";URI=spiffe://cluster.local/ns/istio-system/sa/istio-ingressgateway-service-account"
  }, 
  "json": {
    "answer": 42
  }, 
  "origin": "69.84.111.39,10.100.91.201", 
  "url": "http://httpbin.org/put"
}
$ 

Підсумуємо

Закріпимо найбільш важливі опції Curl для здійснення запитів:

• -X: визначає метод HTTP. Наприклад, curl -X POST url.
• -d: визначає тіло запиту у формі рядка для запитів PUT і POST.
• -H встановлює заголовок запиту. Наприклад, curl -H "Authorization: my-secret-token" url.
• -u: зберігає дані для базової автентифікації.
• -O: зберігає тіло відповіді у локальний файл.
• -i: виводить неформатовану відповідь з заголовками запита включно.

Curl допоможе вам у роботі з API через інтерфейс командного рядка — це може бути ваш власний API або ж сторонній, де потрібна автентифікація. Також з Curl набагато зручніше тестувати запити нашвидкуруч. Для цього не треба писати запити Axios в Node.js або ж налаштовувати Postman. Варто лише знати деякі базові команди, а з цим, сподіваємось, вам допоміг матеріал статті.