Ошибка 401 Unauthorized при первом запросе к Shikimori API почти всегда означает, что токен доступа не передан в заголовке Authorization или приложение не зарегистрировано в настройках аккаунта — проверьте эти два пункта до начала отладки самого кода. Большинство проблем интеграции с API Шикимори возникает не из-за сложности самого интерфейса, а из-за пропущенных шагов настройки OAuth 2.0 и игнорирования лимитов запросов, о которых пойдёт речь ниже.
Shikimori — крупнейшая русскоязычная база аниме и манги, и её открытый API позволяет получать данные о тайтлах, пользователях, списках просмотра и оценках. Документация проекта размещена на официальном сайте в разделе для разработчиков и описывает два подхода: классический REST API и GraphQL. В этой статье разберём, как устроена документация, как пройти авторизацию, какие ограничения действуют и как избежать типичных ошибок.
Где находится документация Shikimori API
Официальная документация доступна на домене shikimori.one в разделе /api/doc и построена на базе Swagger (OpenAPI). Это интерактивный интерфейс: каждый эндпоинт можно раскрыть, посмотреть параметры запроса, структуру ответа и даже выполнить тестовый вызов прямо из браузера. Отдельно существует документация по GraphQL API, которая описывает схему типов и доступные поля.
Документация ведётся на английском языке, что нетипично для русскоязычного проекта, но стандартно для API-сервисов. Если по какому-то методу описание кажется неполным, полезно посмотреть исходный код самого Шикимори — проект имеет открытый репозиторий на GitHub, где можно уточнить реальное поведение эндпоинтов.
- 📄 REST API — основной интерфейс с десятками эндпоинтов: аниме, манга, персонажи, пользователи, клубы.
- 🔍 GraphQL — альтернативный способ запросов с выбором только нужных полей ответа.
- 🧪 Swagger UI — встроенный инструмент для тестирования запросов без написания кода.
- 💻 Открытый исходный код — репозиторий проекта на GitHub для проверки деталей реализации.
Регистрация приложения и авторизация OAuth 2.0
Для работы с методами, требующими авторизации, необходимо зарегистрировать приложение в настройках своего аккаунта Шикимори. Там вы получите client_id и client_secret — пару ключей, без которых невозможно получить токен доступа. Часть публичных эндпоинтов (например, получение информации об аниме) работает и без токена, но с ограниченными лимитами.
Авторизация построена по стандартному протоколу OAuth 2.0 с Authorization Code Flow. Пользователь перенаправляется на страницу согласия Шикимори, подтверждает доступ, после чего ваше приложение получает код и обменивает его на пару access_token + refresh_token. Токен доступа имеет ограниченный срок жизни, поэтому в приложении нужно реализовать механизм обновления через refresh-токен.
Базовый запрос с токеном выглядит так:
curl -H "Authorization: Bearer ВАШ_ТОКЕН" \
-H "User-Agent: ИмяВашегоПриложения" \
https://shikimori.one/api/users/whoami
⚠️ Внимание: обязательно указывайте заголовокUser-Agentс названием вашего приложения. Запросы без него или с браузерным User-Agent могут блокироваться — это одна из самых частых причин ошибок403у начинающих разработчиков.
☑️ Подготовка к работе с Shikimori API
Основные эндпоинты REST API
Структура REST API Шикимори логична: ресурсы сгруппированы по сущностям. Например, GET /api/animes возвращает список аниме с фильтрами, а GET /api/animes/:id — детальную информацию по конкретному тайтлу. Аналогично устроены разделы манги, персонажей, людей индустрии, пользователей и клубов.
Поиск по каталогу выполняется через параметр search, а фильтрация — через параметры kind, status, season, score и другие. Пагинация стандартная: page и limit.
| Эндпоинт | Описание | Авторизация |
|---|---|---|
GET /api/animes | Список аниме с фильтрами и поиском | Не требуется |
GET /api/animes/:id | Детали конкретного аниме | Не требуется |
GET /api/users/:id | Профиль пользователя | Не требуется |
GET /api/users/whoami | Данные текущего авторизованного пользователя | Требуется |
POST /api/v2/user_rates | Добавление записи в список пользователя | Требуется |
Обратите внимание, что часть методов вынесена в версионированное пространство /api/v2/ — это касается, в частности, работы со списками пользователя (user rates). Перед использованием метода сверяйте точный путь в Swagger-документации, так как структура API периодически дорабатывается.
GraphQL API: когда он удобнее REST
GraphQL-интерфейс Шикимори позволяет запрашивать ровно те поля, которые нужны приложению, и объединять связанные данные в один запрос. Это особенно полезно, когда REST-вариант требует нескольких последовательных вызовов: например, получить аниме вместе с жанрами, студиями и скриншотами.
Запросы отправляются методом POST на соответствующий GraphQL-эндпоинт с телом в формате JSON. Пример запроса:
{
animes(search: "Frieren", limit: 3) {
id
name
russian
score
poster { mainUrl }
}
}
Вам стоит учитывать, что GraphQL-схема покрывает не весь функционал REST API — часть операций (особенно изменяющих данные) доступна только через REST. Поэтому в реальных проектах часто комбинируют оба подхода: чтение каталога через GraphQL, действия со списками — через REST.
Лимиты запросов и защита от блокировки
API Шикимори ограничивает частоту запросов с одного аккаунта и IP-адреса. Точные значения лимитов могут меняться, поэтому ориентируйтесь на заголовки ответов и поведение сервера: при превышении лимита возвращается ошибка 429 Too Many Requests. Документация прямо рекомендует добавлять паузы между запросами и не делать параллельных обращений пачками.
Если ваше приложение массово обходит каталог, обязательно реализуйте экспоненциальную задержку (retry with backoff): при получении 429 увеличивайте паузу и повторяйте запрос позже. Игнорирование этого правила приводит к временной блокировке, а при систематических нарушениях возможны ограничения на уровне аккаунта.
⚠️ Внимание: не кешируйте токены и персональные данные пользователей дольше, чем это необходимо для работы приложения. Потерянный или утёкший access_token даёт доступ к действиям от имени пользователя — храните его только на серверной стороне и никогда не вшивайте в клиентский код публичных приложений.
- ⏱️ Делайте паузы между последовательными запросами, особенно при обходе каталога.
- 🔁 Обрабатывайте ответ
429повторной попыткой с нарастающей задержкой. - 📦 Кешируйте редко меняющиеся данные (описания тайтлов, жанры) на своей стороне.
- 🚫 Не распараллеливайте запросы в десятки одновременных соединений.
Типичные ошибки и их диагностика
Разберём коды ответов, с которыми чаще всего сталкиваются при интеграции. Ошибка 401 означает проблему с токеном: он отсутствует, просрочен или не передан в заголовке. Ошибка 403 — доступ запрещён: либо не хватает прав (scope) у токена, либо запрос заблокирован из-за отсутствия корректного User-Agent. Ошибка 404 обычно говорит о неверном пути эндпоинта — проверьте, не используете ли вы устаревший URL из старого туториала.
Отдельный случай — пустые или неожиданные данные в ответе. Например, русское название тайтла может отсутствовать, а поле russian вернуть null. Всегда делайте проверки на пустые значения и используйте английское или ромадзи-название как запасной вариант.
Почему запрос работает в браузере, но не в коде
В браузере запрос идёт с вашей сессией и cookie, а из кода — «чистый». Чаще всего не хватает заголовка Authorization с токеном или User-Agent с именем приложения. Сравните оба запроса через инструменты разработчика (вкладка Network) и перенесите недостающие заголовки в свой код.
Практические рекомендации по интеграции
Начинайте разработку с минимального сценария: получите токен, вызовите /api/users/whoami и убедитесь, что авторизация работает. Затем подключайте остальные методы по одному, логируя полные ответы сервера — это сильно упрощает отладку. Для каталожных данных заранее продумайте слой кеширования: описания аниме меняются редко, и повторные обращения к API за ними только расходуют лимит.
Ключевое правило работы с Shikimori API: один пользователь — одно приложение — корректный User-Agent и уважение к лимитам. Соблюдение этих условий избавляет от подавляющего большинства проблем, с которыми сталкиваются разработчики. Если поведение API отличается от описанного в документации, актуальную информацию стоит искать в репозитории проекта и в сообществе разработчиков Шикимори.
Часто задаваемые вопросы
Можно ли использовать Shikimori API без регистрации приложения?
Да, часть публичных GET-эндпоинтов (каталог аниме, манги, профили пользователей) работает без токена. Однако для действий от имени пользователя — изменения списков, получения приватных данных — регистрация приложения и OAuth-авторизация обязательны.
Чем GraphQL отличается от REST в Shikimori API?
REST использует фиксированные эндпоинты с готовой структурой ответа, а GraphQL позволяет запросить только нужные поля и связанные сущности одним запросом. GraphQL удобен для чтения каталога, но часть операций доступна только через REST, поэтому на практике их часто комбинируют.
Что делать при ошибке 429 Too Many Requests?
Прекратите отправку запросов, выдержите паузу и повторите попытку с увеличенной задержкой. Реализуйте механизм экспоненциального backoff и сократите общую частоту обращений — систематическое превышение лимитов может привести к временной блокировке.
Почему API возвращает 403, хотя токен передан?
Наиболее вероятные причины: отсутствует или некорректен заголовок User-Agent с именем приложения, либо у токена недостаточно прав (scope) для вызываемого метода. Проверьте оба пункта и при необходимости перевыпустите токен с нужными разрешениями.
Где искать актуальную информацию, если документация устарела?
Проверьте исходный код проекта на GitHub — Шикимори разрабатывается открыто, и реальное поведение эндпоинтов видно в коде. Также полезны обсуждения в сообществе разработчиков и история изменений репозитория.