kodik-api-client
kodik-api-client — подробная асинхронная Rust-библиотека для публичного Kodik API. Она покрывает ресурсы /years, /genres, /countries, /qualities/v2, /translations/v2, /list и /search, предоставляет типизированные фильтры и модели ответов, а также поддерживает передачу параметров через GET и POST.[1]
Библиотека не содержит токенов, не выводит их в лог и не включает реальных ключей в примеры. Используйте собственный токен только через переменную окружения
KODIK_API_TOKEN.
| Компонент | Назначение |
|---|---|
hyper + hyper-rustls |
HTTP/1.1 и HTTP/2-клиент с TLS на Rustls; hyper-rustls является транспортным адаптером для Hyper и Rustls. |
tokio |
Асинхронный runtime для сетевых запросов и ожидания лимитера. |
simd-json |
Высокопроизводительное десериализующее чтение JSON-ответов. |
serde |
Строго типизированные модели запросов и ответов. |
governor |
Общий для клонов клиента rate limit; по умолчанию — 3 исходящих запроса в секунду. |
thiserror |
Декларативный публичный тип Error с сохранением вложенных исходных ошибок. |
Установка
После публикации добавьте dependency из crates.io; минимальная поддерживаемая версия Rust (MSRV) — 1.97.1.
[]
= "0.1"
= { = "1", = ["macros", "rt-multi-thread"] }
До первой публикации используйте Git-ветку:
[]
= { = "https://github.com/blassonad/kodik-api", = "feat/rust-kodik-client" }
Локально проект проверяется командой:
Быстрый старт
Выполните поиск фильма с нечётким названием. API-токен передаётся при создании KodikClient, а критерий поиска создаётся как SearchQuery. По документации Kodik хотя бы один критерий поиска обязателен; библиотека проверяет это до обращения к сети.[1]
use ;
async
Надёжность запросов
Клиент безопасен по умолчанию: запрос получает 20-секундный таймаут после ожидания rate limit, а чтение тела ограничено 8 МиБ. Превышение лимита возвращает Error::ResponseBodyTooLarge; таймаут возвращает Error::Timeout. Это не исключает буферизации успешного JSON полностью — она необходима simd-json для разбора среза байтов, — но не позволяет ответу неограниченно занять память.
Настройки можно изменить для конкретного клиента:
use Duration;
use KodikClient;
let client = builder
.request_timeout
.max_response_body_bytes
.build?;
# Ok::
SearchQuery отклоняет Some("") и строки, состоящие только из пробелов, как отсутствующий критерий. ListQuery::limit и SearchQuery::limit принимают только значения от 1 до 100 включительно; 0 и 101+ возвращают Error::Validation до сетевого вызова.
Методы клиента
| Метод | Kodik endpoint | Результат | Особенность |
|---|---|---|---|
years |
/years |
CollectionResponse<YearCount> |
Справочник годов; сортировка YearSort. |
genres |
/genres |
CollectionResponse<LabelCount> |
Поддерживает источник GenreSource. |
countries |
/countries |
CollectionResponse<LabelCount> |
Справочник стран с теми же общими фильтрами. |
qualities |
/qualities/v2 |
CollectionResponse<LabelCount> |
Вторая версия справочника качеств. |
translations |
/translations/v2 |
CollectionResponse<TranslationCount> |
Вторая версия справочника озвучек с ID. |
list |
/list |
ListResponse |
Постраничный обход всей базы по курсору next. |
search |
/search |
SearchResponse |
Нечёткий либо точный поиск названий и ID. |
Каждый метод также имеет пару *_with_method(query, RequestMethod). По умолчанию используется RequestMethod::Get; RequestMethod::Post отправляет ту же кодированную форму в теле application/x-www-form-urlencoded, поскольку Kodik принимает параметры обоими способами.[1]
Запросы и фильтры
Общие ограничения находятся в Filters. Массивы кодируются через запятую. Поля без суффикса _and означают «есть хотя бы одно значение», а соответствующие _and — «есть все значения», как определено в документации API.[1]
| Категория | Значимые поля Filters |
|---|---|
| Типы, годы и перевод | types, year, translation_ids, block_translations, translation_type |
| Идентификаторы и признаки | has_field, has_field_and, camrip, lgbt |
| Страны и жанры | countries, countries_and, genres, anime_genres, drama_genres, all_genres и варианты _and |
| Численные условия | duration, kinopoisk_rating, imdb_rating, shikimori_rating, mydramalist_rating, minimal_age |
| Персоны | actors, directors, producers, writers, composers, editors, designers, operators и варианты _and |
| Аниме и дорамы | rating_mpaa, anime_kind, mydramalist_tags, статусы, anime_studios, anime_licensed_by |
Диапазоны передаются строкой, например duration: Some("40-80".into()) или imdb_rating: Some("7.0-8.5".into()). Это намеренно сохраняет синтаксис API без потери точности.
Пагинация /list
ListResponse содержит next_page. Нельзя выполнять этот URL напрямую: он включает секретный токен в query string. Вместо этого извлеките только курсор через KodikClient::next_cursor, сохраните его в ListQuery::next и пошлите новый запрос библиотекой.
use ;
async
Полный перечень структур, всех полей и семантики доступен в docs/API.md. Рабочие, не содержащие ключа примеры находятся в examples/search.rs и examples/list_all.rs. Процедура публикации в crates.io и создания GitHub Release описана в RELEASING.md.
Лицензия
Проект распространяется по лицензии MIT.