Skip to content

Latest commit

 

History

History
178 lines (118 loc) · 13.6 KB

understand-curl.md

File metadata and controls

178 lines (118 loc) · 13.6 KB
Raw

Глубокое понимание curl

Почти каждый API показывает, как взаимодействовать с API с помощью curl. Поэтому, прежде чем двигаться дальше, давайте немного остановимся и узнаем больше о curl.

Почему curl?

Используем curl для получения веб-страницы

Запросы и ответы содержат заголовки

Распаковка curl запроса API сервиса прогноза погоды

Строки запроса и параметры

Общие команды curl, связанные с REST

Пример curl команды

Опрос

Почему curl?

Одним из преимуществ API REST является то, что вы можете использовать практически любой язык программирования для вызова конечной точки. Конечная точка - это просто ресурс, расположенный на веб-сервере по определенному пути.

Каждый язык программирования имеет свой способ совершать веб-вызовы. Вместо того, чтобы тратить силы, пытаясь показать, как совершать веб-вызовы на Java, Python, C ++, JavaScript, Ruby и т. д., можно просто использовать curl.

curl предоставляет общий, независимый от языка способ демонстрации HTTP-запросов и ответов. Пользователи могут видеть формат запроса, включая любые заголовки и другие параметры. Можно перевести результат в определенный формат для используемого языка.

Используем curl для получения веб-страницы

Как упоминалось ранее, одна из причин, по которой API REST настолько знакомы, заключается в том, что REST следует той же модели, что и веб (см. Что такое REST API?). При вводе http-адреса в адресную строку браузера мы говорим браузеру сделать HTTP-запрос к ресурсу на сервере. Сервер возвращает ответ, а наш браузер преобразует ответ в более визуальное отображение. Но мы также можем увидеть и сырой код.

Чтобы увидеть пример того, как curl извлекает веб-ресурс, откройте терминал и введите следующее:

curl http://example.com

Curl извлечет HTML-код для сайта example.com. Задача браузера - сделать этот код визуально читаемым. curl показывает, что мы на самом деле получаем.

Запросы и ответы содержат заголовки

При вводе адреса веб-сайта мы видим только текст ответа. Но на самом деле происходит гораздо больше процессов. Когда мы делаем запрос, мы отправляем заголовок запроса, который содержит информацию о запросе. Ответ также содержит заголовок ответа.

  1. Для того чтобы увидеть заголовок ответа в запрос curl, добавим ключ -i:
curl http://example.com -i

Заголовок будет включен над телом ответа:

~/projects $ curl http://example.com -I
HTTP/1.1 200 OK
Content-Encoding: gzip
Accept-Ranges: bytes
Cache-Control: max-age=604800
Content-Type: text/html; charset=UTF-8
Date: Tue, 04 Dec 2018 04:35:43 GMT
Etag: "1541025663+gzip"
Expires: Tue, 11 Dec 2018 04:35:43 GMT
Last-Modified: Fri, 09 Aug 2013 23:54:35 GMT
Server: ECS (sjc/4F91)
X-Cache: HIT
Content-Length: 606
  1. Чтобы в ответе получить только заголовок, используем ключ -I
curl http://example.com -I

Заголовок содержит метаданные ответа. Вся эта информация передается в браузер при запросе URL в нашем браузере (например, при просмотре веб-страницы в Интернете), но браузер не отображает эту информацию. Можно просмотреть информацию заголовка с помощью консоли Chrome Developer Tools, перейдя на вкладку Network.

  1. Теперь давайте уточним метод. Метод GET (чтение) подразумевается по умолчанию, когда не указан другой метод, но мы сделаем это здесь явно с параметром -X:
curl -X GET http://example.com -I

При посещении веб-сайта мы отправляем запрос, используя метод GET. Существуют и другие методы HTTP, которые можно использовать при взаимодействии с REST API. Вот общие методы, используемые при работе с конечными точками REST:

HTTP метод Описание
POST Создание ресурса
GET Чтение (получение) ресурса
PUT Обновление ресурса
DELETE Удаление ресурса

Метод GET используется по умолчанию в запросах curl. При использовании curl для выполнения запросов HTTP, отличных от GET, необходимо указывать нужный метод HTTP.

Распаковка curl запроса API сервиса прогноза погоды

Рассмотрим подробнее запрос, который сделали в API сервиса прогноза погоды в предыдущем разделе Создание curl запроса:

curl -X GET -H "Cache-Control: no-cache" -H "Postman-Token: 930d08d6-7b2a-6ea2-0725-27324755c684" "https://api.openweathermap.org/data/2.5/weather?zip=95050&appid=fd4698c940c6d1da602a70ac34f0b147&units=imperial"

У curl есть сокращенные имена для различных опций, которые вы включаете в свой запрос.

Вот расшифровка команд:

  • -Х GET. -X Показывает, что в запросе будет использоваться какой-то метод. Общие параметры: GET, POST, DELETE, PUT. (Также можете увидеть использование --get. Большинство команд curl имеют несколько разных представлений. -X GET также можно записать как --get.)
  • -H Отправляет пользовательский заголовок. Для каждого заголовка пары ключ-значение включаем дополнительный -H.

Строки запроса и параметры

Параметры почтового индекса (zip), идентификатора приложения (appid) и единиц (units) были переданы в конечную точку с помощью «строк запроса». Знак ? добавленный к URL указывает начало строки запроса. Параметры строки запроса - это параметры, которые появляются после знака ?:

?zip=95050&appid=fd4698c940c6d1da602a70ac34f0b147&units=imperial

После строки запроса каждый параметр объединяется с другими параметрами через символ амперсанда &. Порядок параметров в строке запроса не имеет значения. Порядок имеет значение только в том случае, если параметры находятся слева от строки запроса (и, следовательно, являются частью самого URL-адреса). Любые настраиваемые части конечной точки, которые появляются перед строкой запроса, называются [параметрами пути](INSERT LINK) (разберем их позже).

Общие команды curl, связанные с REST

У curl много возможных команд, но при работе с REST API наиболее распространены следующие:

curl Команда Описание Пример
i или --include Включает заголовки ответа в ответ curl -i http://www.example.com
-d или --data Включает данные для публикации на URL. Данные должны быть в кодировке URL. Данные также могут быть переданы в теле запроса. curl -d "data-to-post" http://www.example.com
-H или --header Отправляет заголовок запроса на ресурс. Заголовки являются общими с запросами REST API, потому что авторизация обычно включается в заголовок curl -H "key:12345" http://www.example.com
-X POST Задает метод HTTP для использования с запросом (в данном примере, POST). При использовании -d в запросе, curl автоматически указывает метод POST. С GET-запросами, в том числе HTTP-метод является необязательным, поскольку GET-метод используется по умолчанию curl -X POST -d "resource-to-update" http://www.example.com
@filename Загружает контент из файла curl -X POST -d @mypet.json http://www.example.com

В документации curl есть полный список команд curl.

Пример curl команды

Вот пример запроса curl, который объединяет некоторые из этих команд:

curl -i -H "Accept: application/json" -X POST -d "{status:MIA}" http://personsreport.com/status/person123

Запрос также может быть отформатирован с разрывом строки, чтобы быть более читабельным:

curl -i \
     -H "Accept: application/json" \
     -X POST \
     -d "{status:MIA}" \
     http://personsreport.com/status/person123 \

Разрывы строк является проблемой для Windows, поэтому лучше не форматировать запросы curl.

Заголовок Accept сообщает серверу, что в ответе мы принимаем только формат JSON.

👨‍💻 Опрос

Проверьте свою внимательность. Что означают следующие параметры?

  • -i
  • -H
  • -X POST
  • -d

Использование curl в Терминале или iTerm OS Mac обеспечивают намного более простую работу, чем использование командной строки в Windows. Если серьезно относиться к документации API, работая на ПК, стоит подуматьо переходе с OS Windows. Будет много утилит, которые мы установим при помощи Терминала, который просто работает на Mac. Кроме того, находясь в Силиконовой долине, и используя ПК вместо Mac можно показаться старомодным для окрружающих (см. Почему большинство стартапов покупают MacBook для своих сотрудников).

Для более подробного изучения curl в документировании REST API можно посмотреть REST-esting with curl.

🔙

Go next ➡