Понимание и использование REST API

Скорее всего, вы столкнулись с термином «REST API», если думали о получении данных из другого источника в Интернете, такого как Twitter или Github. Но что такое REST API? Что это может сделать для вас? Как ты это используешь?

В этой статье вы узнаете все, что вам нужно знать об API REST, чтобы иметь возможность читать документацию по API и эффективно их использовать.

Что такое REST API

Допустим, вы пытаетесь найти видео о Бэтмене на Youtube. Вы открываете Youtube, вводите «Бэтмен» в поле поиска, нажимаете «Ввод», и вы видите список видео о Бэтмене. REST API работает аналогичным образом. Вы что-то ищете и получаете список результатов от службы, которую вы запрашиваете.

API — это интерфейс прикладного программирования. Это набор правил, позволяющих программам взаимодействовать друг с другом. Разработчик создает API на сервере и позволяет клиенту общаться с ним.

REST определяет, как выглядит API. Это расшифровывается как «Репрезентативная государственная передача». Это набор правил, которым следуют разработчики при создании своего API. Одно из этих правил гласит, что вы должны иметь возможность получить часть данных (называемую ресурсом), когда вы ссылаетесь на определенный URL-адрес.

Каждый URL-адрес называется запросом , а данные, отправляемые вам обратно, называются ответом .

Анатомия запроса

Важно знать, что запрос состоит из четырех вещей:

1. Конечная точка
2. Метод
3. Заголовки
4. Данные (или тело)

Конечная точка (или маршрут) — это URL-адрес, который вы запрашиваете. Он следует этой структуре:

 root-endpoint/ ? root-endpoint/ ? root-endpoint/ ?

Корневая конечная точка — это начальная точка API, от которого вы запрашиваете. Корневая конечная точка API Github — https://api.github.com , а корневая конечная точка API Twitter — https://api.twitter.com .

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

Вы можете получить доступ к путям так же, как вы можете ссылаться на части веб-сайта. Например, чтобы получить список всех сообщений, помеченных как «JavaScript» в журнале Smashing Magazine, перейдите по https://www.smashingmagazine.com/tag/javascript/ . https://www.smashingmagazine.com/ — это корневая конечная точка, а /tag/javascript — это путь.

Чтобы понять, какие пути вам доступны, нужно просмотреть документацию по API. Например, допустим, вы хотите получить список репозиториев определенного пользователя через API Github. Документы говорят вам использовать для этого следующий путь:

 /users/:username/repos

Любые двоеточия ( : ) в пути обозначают переменную. Вы должны заменить эти значения фактическими значениями при отправке запроса. В этом случае вы должны заменить :username на фактическое имя пользователя, которого вы ищете. Если я ищу свою учетную запись Github, я заменю :username на zellwk .

Конечная точка для получения списка моих репозиториев на Github:

 https://api.github.com/users/zellwk/repos

Последняя часть конечной точки — это параметры запроса . Технически параметры запроса не являются частью архитектуры REST, но вы увидите, что многие API используют их. Итак, чтобы помочь вам полностью понять, как читать и использовать API, мы также поговорим о них. Параметры запроса дают вам возможность изменить ваш запрос с помощью пар ключ-значение. Они всегда начинаются со знака вопроса ( ? ). Затем каждая пара параметров отделяется амперсандом ( & ), например:

 ?query1=value1&query2=value2

Когда вы пытаетесь получить список пользовательских репозиториев на Github, вы добавляете к своему запросу три возможных параметра, чтобы изменить предоставленные вам результаты:

Если вы хотите получить список репозиториев, которые я недавно отправил, вы можете установить sort на push .

 https://api.github.com/users/zellwk/repos?sort=pushed

Как узнать, работает ли эта конечная точка? Что ж, пора попробовать!

Тестирование конечных точек с помощью curl

Вы можете отправить запрос с любым языком программирования. Пользователи JavaScript могут использовать такие методы, как Fetch API и метод jQuery Ajax; Пользователи Ruby могут использовать класс Ruby Net::HTTP, пользователи Python могут использовать запросы Python; и так далее.

В этой статье мы будем использовать утилиту командной строки под названием cURL. Мы используем cURL, потому что документация API обычно пишется со ссылкой на cURL. Если вы понимаете, как использовать cURL, у вас не возникнет проблем с пониманием документации по API. Затем вы можете легко выполнять запросы на предпочитаемом вами языке.

Прежде чем продолжить, убедитесь, что на вашем компьютере установлен cURL. Откройте терминал и введите curl -version . Эта команда проверяет версию cURL, установленную в вашей системе.

 curl --version

Если у вас не установлен cURL, вы получите сообщение об ошибке «команда не найдена». Если вы получили эту ошибку, вам нужно будет установить curl, прежде чем двигаться дальше.

Чтобы использовать cURL, введите curl , а затем конечную точку, которую вы запрашиваете. Например, чтобы получить корневую конечную точку Github, введите следующее:

 curl https://api.github.com

Как только вы нажмете Enter, вы должны получить ответ от Github, который выглядит следующим образом:

Чтобы получить список репозиториев пользователя, вы изменяете конечную точку на правильный путь, как мы обсуждали выше. Чтобы получить список моих репозиториев, вы можете использовать эту команду:

 curl https://api.github.com/users/zellwk/repos

Если вы хотите включить параметры запроса с помощью cURL, убедитесь, что вы добавили обратную косую черту ( \ ) перед ? и = символы. Это потому что ? и = — специальные символы в командной строке. Вам нужно использовать \ перед ними, чтобы командная строка интерпретировала их как обычные символы:

 curl https://api.github.com/users/zellwk/repos\?sort\=pushed

Попробуйте использовать любую команду и выполните запрос! Вы получите аналогичный ответ тому, что вы видели с корневым конечным пунктом Github (но с гораздо большим количеством данных).

JSON

JSON (нотация объектов JavaScript) — распространенный формат для отправки и запроса данных через REST API. Ответ, который Github отправляет вам, также имеет формат JSON.

Объект JSON выглядит как объект JavaScript. В JSON каждое свойство и значение должны быть заключены в двойные кавычки, например:

 { "property1": "value1", "property2": "value2", "property3": "value3" }

Назад к анатомии запроса

Вы узнали, что запрос состоит из четырех частей.

1. Конечная точка
2. Метод
3. Заголовки
4. Данные (или тело)

Давайте рассмотрим остальную часть того, что составляет запрос.

Метод

Метод — это тип запроса, который вы отправляете на сервер. Вы можете выбрать один из следующих пяти типов:

• GET
• POST
• PUT
• PATCH
• DELETE

Эти методы обеспечивают смысл запроса, который вы делаете. Они используются для выполнения четырех возможных действий: Create , Read , Update и Delete (CRUD).

API позволяет узнать, какой метод запроса использовать для каждого запроса. Например, чтобы получить список репозиториев пользователя, нужен GET -запрос:

Запрос GET необходим для получения списка репозиториев от пользователя. Чтобы создать новый репозиторий Github, вам нужен POST -запрос:

Вы можете установить метод запроса в cURL, написав -X или --request , а затем метод запроса. Эта команда ниже пытается создать репозиторий через cURL:

 curl -X POST https://api.github.com/user/repos

Попробуйте запустить этот запрос. Вы получите ответ о том, что требуется аутентификация. (Подробнее об аутентификации позже).

 { "message": "Requires authentication", "documentation_url": "https://developer.github.com/v3" }

Заголовки

Заголовки используются для предоставления информации как клиенту, так и серверу. Его можно использовать для многих целей, таких как аутентификация и предоставление информации о содержимом тела. Вы можете найти список допустимых заголовков в Справочнике HTTP-заголовков MDN.

Заголовки HTTP — это пары "свойство-значение ", разделенные двоеточием. В приведенном ниже примере показан заголовок, указывающий серверу ожидать содержимое JSON.

 "Content-Type: application/json". Missing the opening ".

Вы можете отправлять заголовки HTTP с помощью curl с помощью опции -H или --header . Чтобы отправить вышеуказанный заголовок в API Github, вы используете эту команду:

 curl -H "Content-Type: application/json" https://api.github.com

(Примечание: заголовок Content-Type не является обязательным для работы Github API. Это всего лишь пример, иллюстрирующий, как использовать заголовок с cURL).

Чтобы просмотреть отправленные вами заголовки, вы можете использовать параметр -v или --verbose при отправке запроса, например:

 curl -H "Content-Type: application/json" https://api.github.com -v 

Здесь * относится к дополнительной информации, предоставляемой cURL. > относится к заголовкам запроса, а < относится к заголовкам ответа.

Данные (или «тело»)

Данные (иногда называемые «телом» или «сообщением») содержат информацию, которую вы хотите отправить на сервер. Эта опция используется только с запросами POST , PUT , PATCH или DELETE .

Чтобы отправить данные через cURL, вы можете использовать опцию -d или --data :

 curl -X POST <URL> -d property1=value1

Чтобы отправить несколько полей данных, вы можете создать несколько опций -d :

 curl -X POST <URL> -d property1=value1 -d property2=value2

Если это имеет смысл, вы можете разбить свой запрос на несколько строк \ , чтобы его было легче читать:

 curl -X POST <URL> \ -d property1=value1 \ -d property2=value2

Если вы знаете, как раскрутить сервер, вы можете создать API и протестировать свои собственные данные. Если вы не знаете, но чувствуете себя достаточно смелым, чтобы попробовать, вы можете следовать этой статье, чтобы научиться создавать сервер с помощью Node, Express и MongoDB.

Если вы не хотите раскручивать свой сервер, вы можете зайти на Requestbin.com ( это бесплатно! ) и нажать «создать конечную точку». Вам будет предоставлен URL-адрес, который вы можете использовать для проверки запросов, например https://requestb.in/1ix963n1 , показанный на рисунке ниже.

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

Теперь попробуйте отправить данные в корзину запросов, а затем обновите веб-страницу своей корзины. Вы увидите некоторые данные, например:

 curl -X POST https://requestb.in/1ix963n1 \ -d property1=value1 \ -d property2=value2 

По умолчанию cURL отправляет данные, как если бы они отправлялись через «поля формы» на странице. Если вы хотите отправить данные JSON, вам нужно установить для Content-Type значение application/json , и вам нужно будет отформатировать данные как объект JSON, например:

 curl -X POST https://requestb.in/1ix963n1 \ -H "Content-Type: application/json" \ -d '{ "property1":"value1", "property2":"value2" }' 

И это (почти!) все, что вам нужно знать о структуре запроса.

Теперь помните, когда вы пытались отправить запрос POST через API Github, вы получили сообщение «Требуется аутентификация»? Ну, это потому, что вы не авторизованы для выполнения POST -запроса!

Аутентификация

Вы бы не позволили никому получить доступ к вашему банковскому счету без вашего разрешения, не так ли? В том же духе разработчики принимают меры, чтобы гарантировать, что вы выполняете действия только тогда, когда у вас есть на это полномочия. Это не позволит другим выдавать себя за вас.

Поскольку запросы POST , PUT , PATCH и DELETE изменяют базу данных, разработчики почти всегда помещают их за стену аутентификации. В некоторых случаях GET также требует аутентификации (например, когда вы получаете доступ к своему банковскому счету, чтобы проверить свой текущий баланс).

В Интернете существует два основных способа аутентификации:

1. С именем пользователя и паролем (также называемым базовой аутентификацией)
2. С секретным токеном

Метод секретного токена включает oAuth, который позволяет вам аутентифицировать себя в социальных сетях, таких как Github, Google, Twitter, Facebook и т. д.

В этой статье вы научитесь использовать только базовую аутентификацию с именем пользователя и паролем. Если вы заинтересованы в аутентификации с помощью oAuth, я предлагаю прочитать «Что вам нужно знать об OAuth2 и входе в систему через Facebook» Зака ​​Гроссбарта.

Чтобы выполнить базовую аутентификацию с помощью cURL, вы можете использовать параметр -u , за которым следует ваше имя пользователя и пароль, например:

 curl -x POST -u "username:password" https://api.github.com/user/repos

Попробуйте аутентифицировать себя с помощью имени пользователя и пароля в приведенном выше запросе. После успешной аутентификации вы увидите, что ответ изменится с «Требуется аутентификация» на «Проблемы при синтаксическом анализе JSON».

Это связано с тем, что вы еще не предоставили какие-либо данные (которые требуются для всех запросов POST , PUT , PATCH и DELETE ) на сервер.

Обладая знаниями, которые вы уже получили, вы сможете отредактировать приведенный выше код, чтобы создать репозиторий Github через ваш cURL. Я бы оставил вас, чтобы попробовать это сами!

Теперь поговорим о кодах состояния HTTP и сообщениях об ошибках.

Коды состояния HTTP и сообщения об ошибках

Некоторые из полученных вами ранее сообщений, например «Требуется аутентификация» и «Проблемы при синтаксическом анализе JSON», являются сообщениями об ошибках. Они появляются только тогда, когда что-то не так с вашим запросом. Коды состояния HTTP позволяют быстро сообщить статус ответа. Диапазон от 100+ до 500+. Как правило, числа подчиняются следующим правилам:

1. 200+ означает, что запрос выполнен успешно .
2. 300+ означает, что запрос перенаправляется на другой URL
3. 400+ означает, что произошла ошибка, исходящая от клиента .
4. 500+ означает, что произошла ошибка, исходящая от сервера .

Вы можете отлаживать статус ответа с помощью подробной опции ( -v или --verbose ) или опции заголовка ( -I или --head ).

Например, если вы попытались добавить -I в запрос POST без указания имени пользователя и пароля, вы получите код состояния 401 (неавторизованный):

Если ваш запрос недействителен из-за того, что ваши данные неверны или отсутствуют, вы обычно получаете код состояния 400 (неверный запрос).

Чтобы получить дополнительную информацию о конкретных кодах состояния HTTP, вы можете обратиться к Справочнику по состоянию HTTP MDN.

Версии API

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

Вы можете запросить конкретную версию API двумя способами. Какой способ вы выберете, зависит от того, как написан API.

Эти два способа:

1. Непосредственно в конечной точке
2. В заголовке запроса

Twitter, например, использует первый метод. На момент написания статьи API Twitter был версии 1.1, что видно по его конечной точке:

 https://api.twitter.com/1.1/account/settings.json

Github, с другой стороны, использует второй метод. На момент написания Github API имел версию 3, и вы можете указать версию с заголовком Accept :

 curl https://api.github.com -H Accept:application/vnd.github.v3+json

Подведение итогов

В этой статье вы узнали, что такое REST API и как использовать cURL для выполнения запроса с помощью методов GET , POST , PUT , PATCH и DELETE . Кроме того, вы также узнали, как аутентифицировать свои запросы с помощью параметра -u и что означают статусы HTTP.

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