> For the complete documentation index, see [llms.txt](https://evgenii-afanasev.gitbook.io/ruby-course/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://evgenii-afanasev.gitbook.io/ruby-course/11_network/1_http_api_rest.md).

# Что такое HTTP, API, REST API

## HTTP

HTTP (HyperText Transfer Protocol) - это протокол, который используется для передачи данных в сети Интернет. Он позволяет веб-серверам и веб-клиентам (например браузерам) обмениваться информацией между собой c поомщью запросов. Запрос может содержать такие данные, как адрес (URL), которую вы хотите открыть, и параметры для поиска или фильтрации, а также тело запроса и заголовки. Сервер обрабатывает этот запрос и отправляет обратно ответ, который может содержать HTML-код страницы, изображения, видео и другие данные.

Из чего состоит HTTP запрос:

* Метод - Если представить HTTP запрос в виде объекта ООП, то у него тоже окажутся методы, куда остальные параметры запроса передаются как аргументы. Всего существует 9 методов, но мы подробнее разберем только 4 основных:
  * GET - метод получения информации. Когда вы открываете веб-страницу, ваш браузер отправляет GET запрос на сервер с помощью HTTP и в ответ на него получает HTML страницу, CSS файлы и тд.
  * POST - метод передачи информации на сервер. Каждый раз, когда вы заполняете форму регистрации или какой-либо другой ввод, который сервер должен сохранить у себя, сайт отправялет с помощью HTTP POST запрос.
  * DELETE - метод для удаления данных. Например, вы решили на музыкальной стриминг платформе удалить песню из вашего плейлиста. Сайт или мобильное приложение отправит с помощью HTTP DELELTE запрос.
  * PUT - метод обновления данных. Например, вы захотели изменить профиль в социальной сети, то сайт отправит на сервер PUT запрос.
* Адрес - адрес сайта вы каждый раз вводите в вашей строке браузера для того, чтобы на него зайти. Сам адрес состоит из нескольких компонентов:
  * Протокол - HTTP или HTTPS (подробнее об HTTPS будет в дополнительных материалах)
  * Домен - название сайта, например `ya.ru`, `google.com` и тд. На самом деле серверное приложение понятие не имеет какой у него домен. Домен служит для того, чтобы ваш браузер или приложение обратилось в некий сервис под названием DNS, запросило бы у него IP адрес и отправило по этому IP адресу ваш запрос
  * Относительный путь - та часть запроса, которая следует после домена. Уже непосредственно эта часть запроса обрабатывается серверным приложением
  * Параметры запроса - параметры передаются после знака `?` в конце относительного пути. Параметр выглядит как ключ=значение и передать можно несколько параметров разделяя их символом `&`, параметры не уникальные по ключу, можно передевать один и тот же параметр несколько раз или один раз, но значение через запятую `?key=value1,value2`
* Заголовки - чаще всего их называют родным английским названием Headers. По своей сути они похожи на параметры запроса, тоже поставляются в формате ключ - значение, только в отличии от параметров они не видны пользователю в строке, а отправляются в специальном месте для того, чтобы обезопасить передачу их значений, так как нигде снаружи они не видны.

Хорошо. Допустим наше серверное приложение получило этот запрос, обработало и отправило ответ. Из чего же тогда состоит HTTP ответ ?

* Код ответа. Скорее всего вы сталкивались с ними ранее, когда открывали ресурс с неизвестной страницей и видели сообщение `404 Not found`. 404 - это один из таких кодов. Они служат как сигнал для браузера или другого серверного приложения о статусе ответа на ваш запрос. Наиболее часто встречающиеся статусы:
  * 404 - не найдено
  * 200 - все хорошо
  * 500 - ошибка на стороне сервера
  * 400 - ошибка на стороне клиента
  * 403 - доступ запрещен
* Заголовки. Точно такие же заголоовки как и у запроса, которые служат для передачи мета информации в формате ключ/значение
* Тело - основная часть ответа на запрос, которая содержит полезную информацию. Это может быть как HTML файл, так и текст в формате JSON, XML или просто текст без какого либо формата.

Как это выглядит на живом примере ?

Допустим мы решили открыть в браузере страницу youtube конкретного видеоролика, например такую `https://www.youtube.com/watch?v=C_QZtajkDf0`. Что будет происходить ?

* Браузер разменяет у DNS провайдера адрес страницы `youtube.com` на IP адрес сервера на котором расположено серверное приложение youtube'а
* Браузер отправит GET запрос на сервер по полученному IP адресу и передаст ему следующую информацию:
  * Что ему необходимо содержимое по относительному адресу `/watch`
  * Что ему необходимо видео с кодовым названием `C_QZtajkDf0` с помощью параметра `v=`
  * Если вы авторизованы, то в хеддерах может также передаваться метаинформация, которая поможет серверу распознать, что вы это вы.
* После того как сервер обработает запрос, он отдает результат в виде HTTP кода 200, обозначащий, что запрос успешно обработан, а также тело ответа в виде HTML страницы

## API

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

Например, при использовании сторонних библиотек вы взаимодействуете с ее объектами, которые скрывают внутри себя порой оргомнейший функционал. Для того, чтобы вам было удобно этим функционалом пользоваться, его скрывают за объектами и функциями. Эти самые объекты и фцнкции - это и есть API.

В разработке видеоигр вы, возможно слышали про такой термин как DirectX. Directx это тоже API, но для взаимодействия с более низким уровнем компьютера в виде процессора или видеокарты.

## REST API

REST API это одна из вариаций взаимодействия программ через средства сети. Работает оно по такому же принципу как и браузер, только в качестве ответа возвращается текстовый ответ в формате XML или JSON (в современной разработке в 99% случаев будет встречаться именно JSON). REST API появился по большому счету благодаря популиризации мобильных устройств, так как у мобильного приложения нет особо других способов взаимодействовать с сервером, в отличии от браузера.

Для того, чтобы посмотреть на примеры взаимодействия с REST API, вам будет необходимо установить приложение-клиент с помощью которого вам будет удобнее всего взаимодействовать с такими приложениями. Самым простым способом будет установить расширение VSCode `Thunder Client`.

После установки в вашем меню слева появится иконка в виде молнии. Нажмите на нее.

Попробуем взаимодействовать с популярным REST API приложением для получения информации о погоде.

Для того, чтобы отправить HTTP запрос на REST API вам необходимо:

* Нажать на кнопку `New Request`
* В появившемся окне вверху вы увидете строку для ввода адреса, а также для выбора HTTP метода
* Введите адрес `https://api.open-meteo.com/v1/forecast` и выберете метод `GET`
* В разделе `Query Parameters` добавляются параметры URL адреса
* Добавьте следующие параметры
  * latitude = 55.75 - параметр отвечающий за широту
  * longitude = 37.62 - параметр отечающий за долготу
  * forecast\_days = 1 - на какое кол-во дней необходимо получить прогноз
  * hourly = temperature\_2m - указываем, что хотим в ответе получить температуру
  * hourly = rain - указываем, что хотим получить в ответе кол-во дождевых осадков в мм
* Отправляем запрос, нажав на кнопку `Send`

Теперь посмотрим на ответ, который пришел вам в правой части. Как ранее и говорилось, частой практикой является использование формата JSON для передачи информации. В нем мы обнаружим:

* Наши широту и долготу, которые мы вводили
* hourly\_units - единицы измерения
* hourly - данные, которые мы просили API нам предоставить с разбивкой по часам.

Более подробно с возможностями API вы можете ознакомиться в [официальной документации](https://open-meteo.com/en/docs)

## Задание weather\_info

**в рамках данной главы создавать отдельную директорию и файлы не понадобится**

* Изучите [документацию по API](https://api-ninjas.com/api/geocoding) для определния координат
* Составьте запрос для получения координат города Астана, Казахстан

## Дополнительный материал

* [Простым языком об HTTP](https://habr.com/ru/articles/215117/)
* [HTTP методы](https://developer.mozilla.org/ru/docs/Web/HTTP/Methods)
* [HTTPS. В чем отличие от HTTP](https://selectel.ru/blog/http-https/)
* [HTTP коды](https://developer.mozilla.org/ru/docs/Web/HTTP/Status)