Начало работы

Методы и объекты

API aniu — это интерфейс, который позволяет получать информацию из баз данных aniu.ru, anixart.tv, shikimori.org, kodik.org и animedb.com с помощью http-запросов к специальному серверу. Вам не нужно знать в подробностях, как устроена база, из каких таблиц и полей каких типов она состоит — достаточно того, что API-запрос об этом «знает». Синтаксис запросов и тип возвращаемых ими данных строго определены на стороне самого сервиса.

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

https://aniu.ru/api/v1/account.get?id=1

Рассмотрим отдельно все его составляющие.

  • https:// — протокол соединения.
  • aniu.ru/api/ — адрес API-сервиса.
  • v1/ — версия API
  • account.get — азвание метода API aniu. Методы представляют собой условные команды, которые соответствуют той или иной операции с базой данных — получение информации, запись или удаление. Например, account.get — метод для получения информации о пользователе.

    Все методы разделены на секции. Например, для работы с аниме вам нужны методы секции release, для работы с коллекциями — collections, и так далее. Полный список методов по секциям доступен на этой странице.
  • ?id=1 — параметры запроса. После названия метода нужно передать его входные данные (если они есть) — как обычные GET-параметры в http-запросе. В нашем примере мы сообщаем серверу, что хотим получить данные о пользователе с id=1. Входные параметры всегда перечислены на странице с описанием метода.

В ответ сервер вернет JSON-объект с запрошенными данными (или сообщение об ошибке, если что-то пошло не так). JSON — это формат записи данных в виде пар «имя свойства»: «значение». Если вы раньше не встречались с этим форматом, мы рекомендуем познакомиться с ним, прежде чем продолжить чтение: JSON, Wikipedia

Ответ на наш запрос выглядит так:

{
 "id": 1,
 "name": "Alexey",
 "login": "Alexey",
 "link": "https://aniu.ru/@admin",
 "gender": 2,
 "avatar": "https://aniu.ru/avatars/30349796_1.jpg",
 "status": "Sagiri washing dance",
 "social": {
   "telegram": "mrslink",
   "vk": "mrslink",
   "tiktok": "mrslink"
  },
 "is_banned": false,
 "is_perm_banned": false,
 "ban_reason": null
 ...
 "error": false,
}

Структура ответа каждого метода также строго задана, и при работе с API вы заранее знаете, что в поле id придет число, а в поле name — строка. Такие правила оговариваются на страницах с описанием метода и соответствующих объектов, которые он возвращает в ответе. Например, account.get — здесь описаны входные параметры метода и структура его ответа, а здесь — account подробно расписано каждое поле объекта из ответа.

Объект из ответа может быть не уникален для конкретного метода. Например, объект пользователя с набором полей, содержащих его данные, может возвращаться в ответе от методов account.get, account.search, release.lists и еще нескольких.

Регистрация приложения

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

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

После регистрации приложения вам будут отправлены два ключе, это Application ID и Application Key. Они нужны для авторизации приложения в системе, без них ничего работать не будет

Авторизация пользователя

Aniu — социальная сеть, где есть дружеские связи, настройки приватности и даже черные списки. Многое зависит от того, кто просматривает страницу: кто-то увидит на ней всю ту же информацию, что и владелец, а кто-то — лишь общедоступные данные.

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

В общем случае для идентификации в API используется специальный ключ доступа, который называется access_token. Токен — это строка из цифр и латинских букв, которую вы передаете на сервер вместе с запросом. Из этой строки сервер получает всю нужную ему информацию.

Откройте новую вкладку в браузере и введите в адресную строку такой запрос:

https://aniu.ru/api/v1/account.login?app_id=ВАШ_ID&app_key=ВАШ_КЛЮЧ&client=webapp&redirect_uri=https://aniu.ru/blank.html

ВАШ_ID и ВАШ_КЛЮЧ нужно заменить на Application ID и Application Key вашего приложения. Нажмите Enter. Откроется окно с запросом прав. В нем отображаются название приложения, иконки прав доступа, и ваше имя и логин.

Нажмите «Разрешить». Вы попадете на новую страницу с предупреждением о том, что токен нельзя копировать и передавать третьим лицам. В адресной строке будет URL https://aniu.ru/blank.html, а после # вы увидите дополнительные параметры — access_token и user_id. Токен может выглядеть, например, так:

aaa00000b000c0dd0f0e5rrr00aa0ccc

Токен — это ваш ключ доступа. При выполнении определенных условий человек, получивший ваш токен, может нанести существенный ущерб вашим данным и данным других людей. Поэтому очень важно не передавать свой токен третьим лицам.

Поле user_id содержит id пользователя, для которого получен токен.

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

Для этого введите в адресную строку:

https://aniu.ru/api/v1/account.friends.getOnline?app_key=ВАШ_КЛЮЧ&access_token=

и вставьте после знака "=" Ваш access_token, затем нажмите Enter. В ответе сервер вернет список идентификаторов ваших друзей, которые сейчас онлайн.

Заметьте, вы не указали в запросе, для какого пользователя (user_id) нужно получить список — сервер использовал значение по умолчанию, т.е. ваш идентификатор, который он получил из токена. Для некоторых методов нужно будет указывать user_id пользователя, информации о котором вы хотите получить.

Что дальше?

Вы познакомились с основными понятиями, связанными с API aniu. Дальше все зависит лишь от вашего вдохновения.

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