По просьбе трудящихся я продолжаю расширять возможности телеграммного бота. И если API для кошек и лисей нашлось без проблем, то вот что касается кроликов и сов, здесь всё намного хуже. Простых апишек навроде thecatapi в инернетах не находится.
Но это же не беда - у нас есть Imgur, Flickr, Tumblr... Да даже можно под это дело худо-бедно приспособить google и yandex. Получится не оч, но приспособить можно.
Итак, среди некоторых деятелей Imgur довольно популярен. Так что решено было начать с него. Кроме того, этот сервис покрывает "картиночные" нужды reddit-а, что уже говорит о многом.
Отправляемся читать доки по этой апишке, а оказывается, что есть целых 2 официальных источника информации - это https://api.imgur.com и https://apidocs.imgur.com и если первый объявлен deprecated, то второй содержит не полное описание. Классика.
На apidocs крайне скудно описаны deprecated методы api. И для GET-методов не всегда описаны параметры. А вот на deprecated api.imgur.com информация более полная, в том числе по тем полям, которые в ответах от api я не видел.
Ну да ладно, с источниками знаний разобрались. А что у нас с самим API? - нас же в конце-концов интересует больше результат.
Первым делом меня привлёк метод Gallery Tag Он позволяет сделать выборку по тэгу. Возвращает "объектик" Tag, а в нём среди прочего инфо-мусора есть массив с "объектиками" Gallery Image - это вроде как то, что нам нужно... Но не совсем. Дело в том, что выборка происходит по конкретно заданному тэгу, по одному тэгу... то есть получается довольно широкой. А нам бы несколько тэгов, чтобы получать ровно то, что хочется...
И тут на помощь приходит другой метод - Gallery Search. А это уже намного интереснее - здесь поиск происходит по словам, ровно как на сайте. И есть возможность использования логических операторов AND, OR, скобочек. И возвращается уже знакомый "объектик" Gallery Image. И тут возникает вопрос - нам вобщем-то анимации не нужны в выборке, нас устраивает jpeg и png. Можно, конечно, выкидывать из полученной выборки "картинки" с форматом mp4, но тогда у нас результатов выборки будет несколько меньше.
Внимательно изучив доки я заметил, что теоретически можно на результаты влиять query-параметрами q_type и q_not. Казалось бы - вот оно, счастье! ставим для пробы, что q_type=png и... стоп: в выборке мы получаем энное количество объектов типа gifv с mime-type video/mp4 и приличное количество объектов с mime-type image/jpeg... Что-то не то. Ладно, а что если добавить q_not=anigif? В выборке стало меньше gifv-объектиков. Статистически меньше. То есть без параметров вообще у нас было 10-15 таких элементов (выборка возвращает где-то 65-80 элементов), но если наложить ограничения на запрос, то вернётся всего 2-3 анимированных объекта. Ну да ладно, зато у нас есть для каждого элемента выборки свойство animated и оно выставлено в true для всех, кто gifv. По этому признаку можно отбрасывать лишнее. Ещё один полезный признак - nsfw и он в свойствах для соответствующего контента выставляется в true.
Ладно, теория — это, конечно, хорошо, но хотелось бы перейти к практике.
Первое, что нам надо сделать - это зарегистрировать своё приложение. Анонимно API не работает. Вероятно, подразумевается, что мы можем делать некое количество запросов в определённый промежуток времени, а потом срабатывают ratelimit-ы. Об этом нам говорят соответствующие http-заголовки в ответе от api.
'x-ratelimit-userreset' => '1614462048'
'x-ratelimit-userlimit' => '2000'
'x-ratelimit-userremaining' => '1997'Итак, для работы с API нам надо получить client_id, client_secret, refresh_token и access_token. Для наших поисковых запросов в api нам нужен access_token. Этот access_token имеет привычку иногда протухать. Момент протухания (до какого unix time stamp действителен токен) указывается, когда мы получаем access_token.
Операция регистрации более внятно описана в deprecated-версии документации, нежли в новой. Как минимум, в старом описании не фигурирует какое-то странное приложение, нафиг никому не нужное, они там обходятся стандартным браузером, без смузей и хипстерских подворотов. Остаётся добавить, что в качестве response_type я выбрал token. И ещё один нюанс - в vivaldi авторизация на сайте imgur.com сломана уже давно, а вот в chrome всё работает хорошо. Что называется - "используйте правильный браузер".
Что ещё надо иметь в виду? Хоть и срок протухания access_token-а довольно большой, но на стороне сервера никто не мешает его отозвать, поэтому имеет смысл не только реализовать пере-получение access_token-а по факту истечения срока действия, но и по результатам запроса. То есть, если при "стандартном" запросе у нас вернулось 401 или 403, то надо бы пере-получить access_token и тут-то нам понадобится refresh_token. Мы же не забыли его запомнить? С ним надо пройтись в соответсвующий раздел api и там нам выпишут и новый refresh_token и новый access_token.
Что ещё хотелось бы отметить? Наверно, ровно тот факт, что само api синхронное, но небыстрое - время отрабатывания запроса от 1.6 секунд до 3 секунд, в зависимости от (сложности) запроса. Это надо иметь в виду.
В остальном ничего сложного при работе с api я не обнаружил. Здесь оно вроде как сделано адекватно и согласно REST-у, в отличие от, например, ICQ Bot API. Хотя, конечно, плохо работающие ограничения выборки несколько портят картину.
Пока вроде как с API Imgur всё. Sample client на момент написания статьи у меня уже есть, но, правда, в боте я ещё не успел это всё реализовать. Тем не менее превратить наработки в перловый модуль труда не составит. И остаётся надеяться, что качество выборки и её совпадение с ожиданиями будет удовлетворительное. Моё ручное тестирование показывает довольно высокую степень попадания полученных картинок критериям поиска, что говорит в пользу Imgur-а.