Коротко обо мне
Меня зовут Зел, я разработчик-фрилансер из Сингапура. В свободное от работы время я люблю разбираться в коде и попутно публиковать в своем блоге те интересности, которые я обнаружил или изучил.
Вступление
Скорее всего вам уже приходилось слышать о таком термине, как REST API, особенно если вы сталкивались с необходимостью получения данных из другого источника (такого как Twitter или Github). Но что же все-таки это такое? Что мы можем с этим делать и как мы можем это использовать?
В данной статье вы узнаете все о REST API для того, чтобы работать с ними и читать связанную с ними документацию.
Что же такое REST API?
Давайте представим, что вы пытаетесь найти фильмы о Бэтмене на YouTube. Вы открываете сайт, вбиваете в форму поиска слово «Бэтмен», жмакаете «Окей» и видите список фильмов о супергерое. Похожим образом работает и WEB API. Вы ищите что-то и получаете список результатов от запрашиваемого ресурса.
Дословно API расшифровывается как Application Programming Interface. Это набор правил, позволяющий программам «общаться» друг с другом. Разработчик создает API на сервере и позволяет клиентам обращаться к нему.
REST – это архитектурный подход, определяющий, как API должны выглядеть. Читается как «Representational State Transfer». Этому набору правил и следует разработчик при создании своего приложения. Одно из этих правил гласит, что при обращении к определенному адресу, вы должны получать определенный набор данных (ресурс).
Каждый адрес маршрутом, пакет данных - запросом, в то время как результатирующий ресурс – ответом.
Анатомия запроса
Важно понимать структуру запроса:
- Маршрут отправки
- Тип метода
- Заголовки
- Тело (или данные)
Маршрут – это адрес, по которому отправляется ваш запрос. Его структура примерно следующая:
Root-endpoint - это точка приема запроса на стороне сервера (API). К примеру, конечная точка GitHub – https://api.github.com.
Путь определяет запрашиваемый ресурс. Это что-то вроде автоответчика, который просит вас нажать 1 для одного сервиса, 2 для другого и так далее.
Для понимания того, какие именно пути вам доступны, вам следует просмотреть документацию. К примеру, предположим, вы хотите получить список репозиториев для конкретного пользователя на Git. Согласно документации, вы можете использовать следующий путь для этого:
Вам следует подставить под пропуск имя пользователя. К примеру, чтобы найти список моих репозиториев, вы можете использовать маршрут:
Последняя часть маршрута – это параметры запроса. Технически запросы не являются частью REST-архитектуры, но на практике сейчас все строится на них. Так что давайте поговорим о них более детально. Параметры запроса позволяют использовать в запросе наборы пар «ключ-значение». Они всегда начинаются знаком вопроса. Каждая пара параметров после чего разделяется амперсантом (что-то вроде этого):
Как только вы пытаетесь получить список репозиториев для пользователя, вы добавляете эти три опциональных параметра и после чего получаете следующий результат:
Если же вы желаете получить список моих недавно запушеных репозиториев, вам следует ввести следующее:
Итак, как же понять, что маршруты рабочие? Что ж, пришло время проверить их на практике!
Тестирование при помощи Curl
Вы моете отправить запрос при помощи любого языка программирования. JavaScript может использовать методы вроде Fetch API или JQuery`s Ajax Method. Руби использует другое. И так далее.
В этой статье я буду использовать такую утилитку, как Curl. Дело в том, что она указана в официальной документации для веб-сервисов. Если вы поймете, как использовать эту утилиту, вы поймете, как работать с API. После чего вы можете производить запросы любым удобным для вас языком.
Перед тем, как продолжить, вам следует убедится, что Curl установлен на вашей машине.
Ели же он не установлен, самое время установить. В таком случае вы получите ошибку «command not found».
Для того, чтобы использовать утилиту, необходимо ввести следующее (по примеру):
И как только вы подтверждаете ввод, вы получаете ответ (наподобие этого):
Чтобы получить список пользовательских репозиториев, вам следует изменить запрос по тому же принципу, который был оговорен ранее. К примеру, чтобы получить список моих репозиториев, вам следует ввести следующее:
Если же вы желаете включить параметры запросов, убедитесь, что вы их экранируете. Дело в том, что без экранирования знаки вопроса и равно расцениваются системой как спец. символы и выполнение команды произойдет с ошибкой.
Также попробуйте другие команды и произведите запросы! В результате вы получаете похожие ответы.
JSON
JSON – JavaScript Object Notation – общий формат для отправки и приема данных посредством REST API. Ответ, отправляемый Github, также содержится в формате JSON.
Содержание объекта этого формата примерно следующее:
Возвращаемся к анатомии запроса
Вы изучили, что запрос состоит из четырех частей:
- Маршрут отправки
- Тип метода
- Заголовки
- Тело (или данные)
Теперь же давайте попробуем разобраться с остальным.
Тип метода
Метод обозначает тип производимого запроса, де-факто он является спецификацией операции, которую должен произвести сервер. Всего существует пять типов запросов:
- GET
- POST
- PUT
- PATCH
- DELETE
GET – используется для получения со стороны севера определенного ресурса. Если вы производите этот запрос, сервер ищет информацию и отправляет ее вам назад. По сути, он производит операцию чтения на сервере. Дефолтный тип запросов.
POST – нужен для создания определенного ресурса на сервере. Сервер создает в базе данных новую сущность и оповещает вас, был ли процесс создания успешным. По сути, это операция создания.
PUT и PATCH – используются для обновления определенной информации на сервере. В таком случае сервер просто изменяет информацию существующих сущностей в базе данных и оповещает об успехе выполнения операции.
DELETE – как и следует из названия, удаляет указанную сущность из базы или сигнализирует об ошибке, если такой сущности в базе не было.
Сам же API позволяет указать, какой метод должен быть использован в определенных контекстных ситуациях.
GET запрос в этом случае необходим, чтобы получить список всех репозиториев указанного пользователя. Также можно использовать curl:
Попробуйте отправить этот запрос. В качестве ответа вы получите требование об аутентификации.
Заголовки
Заголовки используются, чтобы предоставить информацию как клиенту, так и серверу. Вообще, их можно использовать для много чего – пример – та же самая аутентификация и авторизация. Найти список доступных заголовком можно на официальной странице MDN.
Видео курсы по схожей тематике:
Заголовки представляют из себя пары ключей-значений. Пример:
Также пример с использованием curl:
(Примечание: заголовок Content-Type в случае Github для работы не является обязательным. Это всего лишь пример использования заголовка в запросе, ничего более.)
Для просмотра отправленных заголовком можно использовать следующее:
Здесь звездочка относится к дополнительной информации, предоставленной посредством curl. > относится к заголовкам запроса, а <, соответственно, - к заголовкам ответа.
Чтобы отправить информацию с curl, используйте следующее:
Для отправки множественных полей, мы можем использовать несколько подобных конструкций:
Также, если необходимо, вы можете разбить ваш запрос на несколько линий для обеспечения большей читабельности:
Если вы знаете, как развернуть сервер, вы можете создать собственный API и протестировать свои запросы. Если же нет, обязательно попробуйте. Существует множество информации, посвященной этому.
Если же желания разворачивать свой сервер нет, попробуйте бесплатную опцию Request bin.
После чего вы получите адрес, который спокойно сможете тестировать.
Убедитесь, что вы создаете свой собственный request bin, если вы хотите протестировать именно ваш запрос. Учитывайте, что дефолтное время существования request bin – 48 часов. Потому те примеры адресов, которые я здесь привожу, на момент прочтения статьи давно как устарели.
Теперь же попробуйте отправить некоторую информацию, после чего обновите свою страницу.
Если все пройдет успешно, вы увидите следующее:
По умолчанию curl отправляет данные так, как если бы они были отправлены посредством полей форм. Если вы хотите отправить данные через JSON, ваш Content-Type должен равняться application\json, впоследствии вам необходимо отформатировать данные в виде JSON-объекта.
По сути, это все, что вам необходимо знать о структуре запроса.
Теперь давайте вспомним об аутентификации. Что же это такое и для чего она нужна?
Аутентификация
Вы бы не позволили никому чужому получить доступ к вашему банковскому счету без специального разрешения, не так ли? По такому же принципу разработчики не позволяют неавторизированным пользователям производить на сервере все, что им вздумается.
Так как POST, PUT, PATCH, DELETE запросы изменяют базу данных, разработчики должны всегда быть на страже неавторизированного доступа к ним. Впрочем иногда GET запросы также требуют аутентификации (к примеру, когда вы желаете посмотреть состояние вашего банковского счета).
В случае с вебом существует два способа представиться системе:
- Через ник и пароль (базовая аутентификация)
- Через секретный токен
Секретный токен позволяет представить вас системе через соц. Сети по типу Github, Google, Twitter и так далее.
Здесь же я рассмотрю только базовую аутентификацию.
Для произведения базовой аутентификации вы можете использовать следующее:
Попробуйте залогиниться под свой профиль по запросу, указанному выше. Как только вы успешно войдете в свой профиль, вы увидите ответ «problems parsing JSON».
Почему? Все просто: системе-то вы представились, но – вот беда – ничего полезного ей не предоставили. Все типы запросов требуют определенной информации.
Теперь же давайте поговорим о статус-кодах и возможных ошибках.
Статус-коды и возможные ошибки
Некоторые из сообщений, приведенных выше, как раз-таки и относятся к кодам ошибок. Логично, что они появляются только, когда что-то идет не совсем так, как было запланировано. Что же касательно статуса кодов, они позволяют вам познать успех (или неудачу) при выполнении определенного запроса. Бывают статус-коды от 100 до 500+. В целом их можно разделить на следующие группы:
- 200+: запрос успешен
- 300+: запрос перенаправлен на другой маршрут
- 400+: ошибка на стороне клиента
- 500+: ошибка на стороне сервера
Вы можете отладить статус ответа при помощи –v или –verbose. К примеру, я попытался получить доступ к определенному ресурсу без авторизации. Следовательно, я поймал ошибку:
В случае же, когда запрос не верен по причине ошибки в самой передаваемой информации, вы получаете статус-код 400:
Версии API
Время от времени разработчики обновляют свои API. Порой обновления могут быть такими сильными, что разработчик желает выпустить релиз новой версии. В таком случае, если ваше приложение ломается, это происходит по причине, что вы писали код с учетом старого компонента, тогда как новый несколько отличается в плане реализации.
Бесплатные вебинары по схожей тематике:
Запросить текущую версию API можно двумя путями.
- Через маршурт
- Через заголовок
К примеру, Твиттер использует первый метод. На момент написания версия Твиттер API была 1.1.
С другой стороны, GitHub использует другой способ:
В заключение
В этой статье мы рассмотрели, что такое REST API и как его можно использовать совместно с curl. Кроме того, вы также выучили, как залогиниться при помощи запроса и что такое статус-код.
Я искренне надеюсь, что эта статья позволила вам повысить свой уровень общих и не очень познаний касательно такого немаловажного аспекта веб-разработки. Буду рад любым вашим комментариям здесь.
Автор перевода: Евгений Лукашук
Еще больше материалов по данной теме:
ASP.NET Core Web API. Практический курс
Статьи по схожей тематике
