Взаимодействие с внешними API

Введение

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

Большинство популярных сервисов предоставляют доступ к своим API, благодаря чему разработчики могут взаимодействовать с ними (сервисы заинтересованы в этом, если вы можете привести больше людей, которые станут пользоваться их продуктом). Facebook, Twitter, Instagram, Flickr, Dropbox, AirBnB... У всех них есть API. Просто погуглите "company X API docs" и вы найдете на каждом из этих сайтов раздел для разработчиков.

Если вы начнете изучать документацию к API, иногда это может быть слишком большим объемом данных, поскольку материал предполагает, что вы знаете, что делаете. Тем не менее, у иных API документация лучше, чем у других. Так же в них есть элементы, свойственные практически для каждого API. Чем больше вы работаете с ними (и понимаете процесс аутентификации), тем проще становится со временем. Вы быстро освоитесь.

В этом уроке мы расскажем о некоторых основных шагах, которые свойственны многим API, и сделаем поверхностный обзор некоторых методов аутентификации в API, например, Omniauth. Постарайтесь получить максимальное понимание принципов и используйте документацию для каждого гема или API при работе с ними. Если вы найдете классный бесплатный обучающий ресурс об API, пожалуйста, дайте нам знать (оставьте комментарий к этому уроку или напишите на frey@list.ru)!

Пункты для размышления

Постарайтесь ответить на предложенные вопросы. После выполнения задания попробуйте ответить на них ещё раз

  • Как лучше всего найти документацию к API?
  • Какие шаги вам почти всегда нужно будет проходить, настраивая ваше приложение для использования API?
  • Что такое ключ API?
  • Как обычно контролируется API?
  • Как избежать включения секретного ключа API в ваш репозиторий на Github (например, сохранения его в вашем коде)?
  • Почему важно знать, какую версию API вы используете?
  • Что такое RESTful API и почему он делает вашу жизнь проще?
  • Что такое (в общих чертах) OAuth?
  • Почему пользователь может предпочесть войти на ваш сайт через Facebook вместо того, чтобы зарегистрироваться через обычную регистрацию?
  • Как (в общих чертах) этот процесс выглядит с точки зрения пользователя?
  • Как (в общих чертах) этот процесс выглядит с вашей (разработчика приложения) точки зрения?
  • Какие основные правила, помогающие не дергать API по пустякам, вы знаете?
  • Что такое OmniAuth и почему это экономит вам кучу времени и нервов?
  • Что такое SDK и почему это полезно при работе с API?

Первые шаги

Вам нужно будет зарегистрировать себя и ваше приложение у провайдера API. Таким образом они смогут мониторить то, как вы используете их интерфейсы. Обычно существует бесплатный план использования, который становится платным, когда вы превышаете свои лимиты, выраженные в количестве загруженных мегабайт, количестве запросов или количестве транзакций (например). Обычно, даже если вы пользователь их сервиса, вам придется отдельно регистрироваться на их портале для разработчиков.

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

Так же вы можете получить "секретный ключ" или подобным образом названный код. В то время, как ключ API обычно публичен, секретный ключ является дополнительным слоем безопасности, который требуется для безопасного подключения к API и вы будете использовать его, чтобы сгенерировать зашифрованный токен, который аутентифицирует посылаемые вами запросы. Вам придется убедиться, что вы не включили этот секретный ключ в ваш репозиторий на Github! Используйте гем figaro или переменные окружения, чтобы передавать ключ на сервер вместо того, чтобы прописывать его в коде напрямую.

Ограничение API и ключи безопасности

Большая часть API требует разных типов "безопасности" для разных запросов:

  1. Вы можете делать безобидные запросы вроде получения твитов (для API Твиттера, конечно же) прямыми и неаутентифицированными GET-запросами. Вы можете делать их из браузера, командной строки или откуда-либо еще. Этот тип запросов к API редко ограничен необходимостью аутентификации.
  2. Следующий слой - это отправка запросов, включающих ваш ключ API. Это все еще довольно безобидные вещи (вроде получения публичных данных), ограниченные тарифными планами API.
  3. Более чувствительные запросы, вроде получения данных о конкретном пользователе или отправка/изменение/удаление данных скорее всего потребуют от вас использования аутентификации, включающей ваш секретный ключ. Мы поговорим об этом в проекте. Ограничения для этих запросов зависят от тарифных планов API.
  4. Зачастую, вам будет необходимо делать запросы от имени пользователя. Например, для показа личного кабинета пользователя со всеми его твитами и записями в Facebook потребуется запросить данные от Twitter и от Facebook. Такой пример потребовал бы МНОЖЕСТВА запросов в базу пользовательских данных, но, к счастью, вы можете сделать запрос от лица пользователя, спросив его разрешения. Мы поговорим об этом позже, но если в общих чертах, то вы авторизуетесь от лица пользователя в API, затем провайдер дает вам уникальный пользовательский токен, который необходимо использовать для осуществления запросов от лица пользователя. Ограничения для таких запросов, как правило, значительно менее жестки, поскольку они индивидуальны для каждого пользователя. Мы обычно используем протокол OAuth для таких случаев, как описано ниже.

Версии

Технические компании, особенно, если они уже имеют некоторую историю, как правило имеют несколько версий своего API. Обычно первая версия является черновой и создается на старте, после чего дорабатывается до полноценной, но оригинальная все еще поддерживается, поскольку многие приложения, вероятнее всего, уже используют её.

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

RESTful API

Так же, как ваши роуты должны быть настроены соответственно принципам RESTful, должен быть настроен и API. В наши дни большинство API придерживаются этих принципов, подразумевая, что GET/PUT/PATCH/DELETE запросы вернут соответствующие результаты. Приятно, что при настройке роутов в вашем приложении соответственно RESTful, ваш API будет соответственно RESTful.

Работа с RESTful API по меньшей мере уменьшает количество потраченных нервов, поскольку вы можете предположить, что вам нужно сделать и затем прочитать в документации, как конкретно и в каком формате вы получите результаты запроса. Например, так же, как вы ожидаете, что GET-запрос к роуту /users в вашем приложении вернет вам страницу со списком всех пользователей, GET-запрос к RESTful API для того же роута, вероятнее всего, вернет вам JSON или XML-объект, содержащий всех пользователей (или, по крайней мере, их часть, если результат разбит на страницы).

Oauth вход через API

Вы видели сайты, которые предлагают вам войти, используя Facebook, Twitter или LinkedIn. После входа через один из таких сервисов третьей стороны вы магическим образом получаете новый аккаунт без необходимости регистрироваться, вводя пароль.

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

Это имеет два прекрасных сценария для использования - вход пользователя при помощи третьего сайта вроде Facebook и осуществление запросов или отправки данных от имени пользователя.

В первом случае вы не получаете пароль пользователя от его аккаунта на Facebook. Он перенаправляется на сайт Facebook, чтобы войти, где далее он позволяет использовать некоторые свои данные (вы указываете, какие данные вам нужны при настройке этого процесса). Facebook обращается к вам (отправляя запрос к указанному вами URL, передавая необходимые данные) и дает вам специальный ключ доступа для этого пользователя. Вы можете использовать его чтобы в дальнейшем получить дополнительные данные, доступ к которым разрешил пользователь (например, его имя и email). Теперь вы можете создать нового пользователя в своей базе данных, внеся в неё полученные данные, и все будут относительно счастливы.

С точки зрения пользователя, ему нужно помнить только пароль от Facebook, чтобы войти на ваш сайт. Ему так же не нужно доверять вам свой пароль. Пока он доверяет Фейсбуку, он может использовать ваш сайт. Так же, если ваш сайт делает плохие вещи с пользовательскими данным (например, когда SocialCam спамил всех подряд в таймлайн Facebook некоторое время), пользователь может сказать Фейсбуку запретить вам использовать его данные и Фейсбук отключит ваш доступ по секретному токену, который он вам выдал.

С точки зрения Facebook, они сохраняют контроль над пользователем и еще глубже проникают в его жизнь (хорошо это или плохо).

Овладев пользовательским токеном, вы получаете возможность делать запросы и отправлять данные, основываясь на разрешениях Фейсбука (и пользователя). Это может включать запросы о друзьях пользователя, публикацию записей в их таймлайн или отметку "Нравится" на какой-нибудь из записей. Вам нужно лишь включить этот токен в ваш запрос на аутентификацию.

Ограничения

Каждый сайт, в дополнение к ограничениям своего API, имеет правила использования. Это обычно включает в себя то, что вам позволено делать с получаемыми данными. Например, они, скорее всего, не разрешат вам хранить все их данные в вашей собственной базе данных. Так же они вряд ли позволят вам рассылать спам или что-либо еще, вредящее UX. В первую очередь вы должны руководствоваться здравым смыслом, но не забудьте так же ознакомиться и с правилами использования, чтобы узнать детали. В общем, если вы собираетесь портить пользовательский опыт или собирать их драгоценные данные, вы не можете этого делать.

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

Основы OAuth 2.0

OAuth 2.0 на самом деле довольно сложен, так что мы поговорим лишь об основном процессе. Вам не придется беспокоиться о том, как конкретно это работает, пока вы не начнете разработку с его использованием или пока не попытаетесь создать собственный API, который будет использовать OAuth. Вам придется понять шаги, из которых состоит пользовательский опыт, поскольку пользователь - это причина, по которой вы создаете приложение.

В общих чертах (все еще используем Фейсбук в качестве примера):

  1. Пользователь пытается получить доступ к странице вашего приложения и вы просите его залогиниться
  2. Пользователь выбирает опцию "Войти через Facebook"
  3. Пользователь перенаправляется на страницу Facebook, спрашивающую его, дает ли он разрешение на использование запрошенных вами данных и просящее его залогиниться. URI будет содежать параметры, которые сообщат Фейсбуку о том, какое приложение запрашивает достууп и, скорее всего, на какой URI он должен отправить ответ (или, возможно, вы указали его (URI) во время регистрации приложения на Facebook).
  4. Пользователь решает, что ваше приложение выглядит интересно и разрешает вам видеть свой email и публиковать записи в свой таймлайн. Он входит в свой аккаунт на Facebook. Facebook создает авторизационный код и отправляет его обратно в ваше приложение по указанному адресу. 5.Пользователь ждет, пока ваше приложение примет этот авторизационный код и использует его, чтобы запросить полезные данные у Facebook. Facebook убеждается, что ваше приложение - то самое, через которое авторизовался пользователь, затем методом POST возвращает вам уникальный аутентификационный токен для пользователя (который, скорее всего, истечет в течение 90 дней) и все данные, которые вы у него запрашивали (например, email).
  5. Вы сохраняете уникальный пользовательский токен в базе данных и используете его вместе с ключом(или ключами) вашего приложения, чтобы делать последующие запросы от имени пользователя.

Посмотрите этот короткой обзор OAuth 2.0, чтобы получить общее представление. Затем прочтите это более детальное объяснение от tutsplus.com.

Реализация OAuth 2.0 в Rails -- используйте Omniauth!

Это звучит ужасно сложно! Кто-то должен был сделать для этого гем...

К счастью, кто-то сделал. Много кто, на самом деле. Существует общий гем, воплощающий необходимый функционал OAuth: он называется omniauth (документация доступна на Github) и отдельные гемы, каждый из которых реализует конкретную стратегию аутентификации для каждого крупного API (список доступен ЗДЕСЬ). Однажды использовав одну из стратегий, вы будете чувствовать себя комфортно с любой из них.

Мы оставим использование Omniauth для проектов, поскольку это намного проще изучать на практике, чем читая кучу пунктов.

SDK

В дополнение к или вместо доступа к API многие компании предоставляют SDK (software development kits или наборы для разработки программного обеспечения). Обычно это библиотеки на javascript, которые содержат весь необходимый для доступа к их API код. Это может быть полезно, поскольку вы сможете получить доступ к API, используя простые методы javascript вместо того, чтобы работать с этим на бэкенде. Обратная сторона использования SDK заключается в том, что увеличивается количество кода, который необходимо поддерживать и вы вынуждены использовать соглашения авторов SDK для всего, что с ним связано.

Мы не будем детально разбирать SDK в этом курсе, но о них обычно можно узнать, читая документацию к API.

Ваши задания

  1. Посмотрите этот Railscast по использованию Omniauth для доступа к авторизации через Twitter.
  2. Прочтите документацию Omniauth
  3. Выберите любой понравившийся API или веб-продукт, который вы используете практически каждый день (например, Google, Facebook, Instagram...). Погуглите их доки (например, "instagram api documentation") и бегло просмотрите их. Документация разных продуктов может отличаться по качеству (со временем вы поймете, что это значит), но она станет источником понимания, какие методы вы можете вызывать, что они вернут, как регистрировать ваше приложение, чтобы получить ключ API и множества других важных вещей.

Заключение

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

Работа с внешними апи может быть невероятно продуктивной и полезной, поскольку вы можете воплощать функционал, на который другие потратили множество времени. Так же она может быть невероятно раздражающей и разочаровывающей, поскольку все API разные и вам придется полагаться на гемы, которые работают, не показывая вам внутренних механизмов и процессов, из-за чего вы не можете быть точно уверены, что происходит. Со временем, вы начнете видеть много общего между разными API, процесс работы с ними будет становиться все более и более комфортным. Чтобы помочь вам в этом, в следующем проекте мы предлагаем вам поработать с API, а ваш финальный проект будет включать реализацию регистрации и входа через API.

Дополнительные ресурсы

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

Поделиться уроком: