Доступ к внешнему 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.

Доступ к JSON-API

Теперь давайте обратимся к реальному JSON-API. В этом примере мы будем использовать 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 Справочник API
• Введение в ReQL
• Lambda-функции в RethinkDB