Доступ к внешним API

Примечание: в следующих примерах используется драйвер JavaScript. Обратитесь к справочному руководству команды r.http для документации по другим языкам.

RethinkDB предоставляет команду r.http для прямого доступа к внешним API из базы данных. Поскольку многие API принимают и возвращают JSON, RethinkDB является удобной платформой для обработки и анализа данных API, как в интерактивном режиме, так и в работающих приложениях. Убедитесь, что вы никогда не используете эту команду для URL, предоставленных пользователем.

Основные возможности

Давайте попробуем что-то очень простое — доступ к веб-сайту. Введите следующую команду в Data Explorer и нажмите «Запустить» (или запустите её из драйвера RethinkDB):

r.http('www.google.com')

Команда r.http отправит запрос к www.google.com напрямую из базы данных и вернёт строку с исходным кодом домашней страницы Google.

Доступ к API JSON

Теперь давайте обратимся к реальному API JSON. В этом примере мы будем использовать GitHub — платформу для совместной разработки, которая размещает тысячи открытых проектов. Пользователи GitHub могут выразить интерес, поставив звездочки на проекты и подписавшись на других пользователей. GitHub называет пользователей, поставивших звездочки на другие проекты, «stargazers».

Давайте найдём самых влиятельных пользователей GitHub, проявивших интерес к RethinkDB. Сначала получим список stargazers RethinkDB:

r.http('https://api.github.com/repos/rethinkdb/rethinkdb/stargazers')

Этот запрос обращается к GitHub и возвращает массив документов JSON. RethinkDB работает напрямую с JSON, и что действительно удобно в r.http, так это то, что его вывод ничем не отличается от любого другого запроса. Вы можете использовать команды ReQL для выполнения операций над результатом r.http, как и над стандартной таблицей RethinkDB!

Например, давайте посчитаем количество возвращённых API результатов:

r.http('https://api.github.com/repos/rethinkdb/rethinkdb/stargazers').count()

Или, давайте извлечём имена пользователей и идентификаторы, и отсортируем массив в порядке возрастания по идентификаторам пользователей:

r.http('https://api.github.com/repos/rethinkdb/rethinkdb/stargazers')
 .pluck('login', 'id').orderBy('id')

Вы можете объединить любое количество команд ReQL для выполнения задач манипулирования данными. Поскольку ReQL специально разработан для запросов и модификаций JSON, он также является отличным языком для работы с веб-сервисами!

Хранение и обогащение данных API

Поскольку вы будете выполнять больше манипуляций с данными, вы, возможно, захотите сохранить результаты вызова API в базе данных. Давайте создадим таблицу stargazers и вставим в неё stargazers RethinkDB:

r.tableCreate('stargazers');
r.table('stargazers').insert(
  r.http('https://api.github.com/repos/rethinkdb/rethinkdb/stargazers'));

Теперь мы хотим отсортировать stargazers RethinkDB по влиянию. При запросе stargazers из GitHub API не включает количество подписчиков для каждого stargazer, но он включает поле url, специфичное для каждого stargazer. Если вы перейдёте по этой ссылке, API GitHub вернёт дополнительную информацию о пользователе, включая количество его подписчиков.

Давайте обновим наши данные stargazer с этой дополнительной информацией:

r.table('stargazers').update(r.http(r.row('url')), {nonAtomic: true})

Команда обновления пройдёт по каждой строке и отправит запрос API к URL GitHub для данного пользователя, извлечёт соответствующие данные и обновит информацию о пользователе этими данными!

Теперь мы можем отсортировать stargazers по количеству подписчиков!

r.table('stargazers').orderBy(r.desc('followers'))

Пагинация

Вышеупомянутые вызовы возвращают лишь несколько десятков stargazers, в то время как RethinkDB содержит тысячи. Большинство API выполняют пагинацию для больших наборов результатов, и GitHub не является исключением. Команда r.http имеет встроенную поддержку пагинации через аргументы page и pageLimit. Давайте получим десять страниц stargazers из GitHub вместо одной:

r.http('https://api.github.com/repos/rethinkdb/rethinkdb/stargazers',
       { page: 'link-next', pageLimit: 10 })

Аргумент page принимает тип механизма пагинации, используемого API. В данном случае GitHub использует стандартный механизм заголовков ссылок link-next, но вы также можете указать собственные схемы пагинации для необычных API. Аргумент page-limit определяет количество страниц, которое вы хотите получить. Для получения дополнительных сведений обратитесь к справочнику API.

При включении пагинации в r.http, вместо возвращения массива документов RethinkDB возвращает поток, к которому вы можете получить доступ в драйвере через обычный API курсора. Это важно, потому что пагинация происходит лениво — RethinkDB будет запрашивать новые страницы по мере итерации по курсору, чтобы минимизировать количество вызовов API.

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

Большинство API поддерживают какую-либо форму аутентификации и ограничения скорости. Команда r.http поддерживает распространённые формы аутентификации (см. справочник для получения более подробной информации). Например, вот как вы можете использовать токены GitHub с базовой аутентификацией:

r.http('https://api.github.com/users/coffeemug', {
       auth: {
           user: GITHUB_TOKEN,
           pass: 'x-oauth-basic'
       }
})

Подробнее

Просмотрите следующие ресурсы, чтобы узнать больше о ReQL и r.http:

• r.http справочник
• Введение в ReQL
• Lambda-функции в RethinkDB