Skip to main content

Crate shikimori_api

Crate shikimori_api 

Source
Expand description

§shikimori-api

shikimori-api — типобезопасный асинхронный Rust-клиент официального Shikimori REST API v1/v2. Crate предоставляет отдельно типизированные query DTO, JSON request DTO и response-модели для каждого опубликованного REST-маршрута двух версий API.

Границы поддержки. Crate намеренно не реализует GraphQL и OAuth authorization, refresh или revoke flow. Для защищённых REST-вызовов передайте уже выданный access token в ClientConfig::builder. Официальная документация рекомендует GraphQL для новых интеграций, однако REST v1/v2 остаётся доступным и полностью покрывается данным crate. 1 2

§Быстрый старт

Ниже приведён безопасный публичный GET-пример. Он компилируется как doctest, но не выполняется автоматически.

use shikimori_api::{ClientConfig, ListAnimesQuery, ShikimoriClient};

let client = ShikimoriClient::new(
    ClientConfig::builder("my-shikimori-app/0.1")
        .build()?,
);

let animes = client
    .list_animes(ListAnimesQuery {
        search: Some("Cowboy Bebop".into()),
        limit: Some(10),
        ..Default::default()
    })
    .await?;

for anime in animes {
    println!("#{}: {}", anime.id, anime.name);
}

§Конфигурация и авторизация

ClientConfig строится через ClientConfig::builder. Builder требует осмысленный непустой User-Agent; Shikimori требует передавать имя OAuth2 application и прямо запрещает имитировать браузер. 1

use shikimori_api::{ClientConfig, ShikimoriClient};

let client = ShikimoriClient::new(
    ClientConfig::builder("my-shikimori-app/0.1")
        // Получение token — ответственность вашего OAuth2-клиента.
        .access_token("access-token-obtained-elsewhere")
        .build()?,
);
assert!(client.has_access_token());

Bearer token отправляется в Authorization только при его явной настройке. Token не включается в Error и ApiError. Требуемый scope зависит от маршрута; Rust-клиент не подменяет серверную проверку прав.

§Ограничение частоты и параллелизм

По умолчанию ShikimoriClient одновременно применяет два общего для всех clones limiter: 5 запросов в секунду и 90 запросов в минуту, как определено Shikimori. 1 Перед каждым HTTP-вызовом клиент ждёт разрешения обоих limiter. Это означает, что client.clone() безопасен для конкурентных задач Tokio: clones не обходят общий лимит.

Клиент не выполняет скрытых повторов. Такой выбор предотвращает неявное дублирование POST/PATCH/PUT/DELETE. При 429 ApiError::retry_after_seconds хранит числовой Retry-After, если его вернул сервер; вызывающий код сам выбирает безопасную retry policy.

§Модули и маршруты

РазделЧто предоставляет
ShikimoriClientЕдинственный async клиент; все endpoint methods реализованы как inherent methods этого типа.
v1Справочник REST API v1: каталог, клубы, комментарии, темы, users, legacy user rates, styles, videos и другие ресурсы.
v2Справочник REST API v2: ignore actions, moderation requests, episode notifications и актуальный CRUD user rates.
Input structuresПубличные query, JSON body и enum-input структуры re-exported с crate root.
typesПубличные модели успешных response bodies и вложенных ресурсов.
Error / ApiErrorТипизированные transport, codec и HTTP API ошибки.

Полная таблица HTTP method → URI → Rust method → input → response → scope находится в endpoint matrix. Расширенные пояснения полей и wire contract находятся в API reference.

§Input и wire-format

Каждый query/body имеет отдельный Rust type вместо универсального JSON map. Например, ListAnimesQuery поддерживает все документированные catalog filters, а ListValue выражает включение и исключение CSV-фильтра (tv,!movie) без ручной строковой конкатенации.

use shikimori_api::{AnimeKind, ListAnimesQuery, ListValue};

let query = ListAnimesQuery {
    kind: Some(vec![
        ListValue::Include(AnimeKind::Tv),
        ListValue::Exclude(AnimeKind::Movie),
    ]),
    ..Default::default()
};

JSON request bodies сериализуются simd_json + Serde. Legacy nested wrappers сохраняются: CreateCommentRequest формирует { "comment": { ... } }, CreateUserRateRequest — { "user_rate": { ... } }. Query и multipart/form-data для user-image upload кодируются crate без дополнительной URL/form dependency.

§Модели и совместимость

В публичных моделях Anime, Manga, Character, Person, Topic, Comment, UserRate и других стабильные поля типизированы. Там, где REST server может добавлять новые строковые значения, output fields сознательно сохраняются как String/Option<String>: это не превращает добавленный сервером enum value в ошибку десериализации.

Даты остаются строками wire-format, а types::FlexibleDate допускает legacy неоднородные person-date значения. Такой подход соответствует примерам официальной документации, где person date может быть объектом {} вместо ISO-строки. 3

§Ошибки

Все async методы возвращают Result<T>.

use shikimori_api::{Error, ShikimoriClient};

match client.anime(1).await {
    Ok(anime) => println!("{}", anime.anime.name),
    Err(Error::Api(api)) if api.status == 429 => {
        eprintln!("Подождите {:?} секунд", api.retry_after_seconds);
    }
    Err(error) => eprintln!("Запрос не выполнен: {error}"),
}
ВариантЗначение
Error::ConfigurationНекорректный base URL, пустой token либо User-Agent.
Error::Transport / Error::BodyОшибка TLS/соединения или чтения HTTP body.
Error::JsonResponse/body не соответствует ожидаемой Serde model.
Error::ApiНе-2xx response Shikimori; содержит HTTP status, parsed errors, body и Retry-After.

§Пагинация

Shikimori предупреждает, что запрос N элементов пагинируемого API в большинстве случаев может вернуть N+1 при существовании следующей страницы. Crate возвращает серверный массив как есть и не обрезает последний элемент. 1 Используйте endpoint-specific query input (PageLimitQuery, PageLimit30Query, ListUsersQuery, ListUserRatesV2Query и т. п.) и интерпретируйте результат согласно этой семантике.

§Deprecated v1 API

Полнота покрытия включает deprecated v1 routes. Там, где у Shikimori есть replacement, методы несут #[deprecated] и rustdoc note: legacy ignores заменяются v2 ignore actions, а legacy v1 user-rate CRUD — соответствующими методами v2. Аналогично, search_animes и search_mangas сохранены для совместимости, но для новых вызовов используйте list routes с полем search.

§Проверка документации

cargo doc --no-deps --all-features
cargo test --doc --all-features

Все сетевые примеры помечены no_run: Cargo проверяет их актуальность и компилируемость, не создавая/не меняя данные Shikimori.

§References

Modules§

types
Типизированные response-модели и общие ресурсы Shikimori REST API. Публичные модели ответов Shikimori API.
v1
Namespace containing all REST v1 operations. REST-методы Shikimori API v1.
v2
Namespace containing all REST v2 operations. REST-методы Shikimori API v2.

Structs§

AbuseRequestInput
Структура данных публичного контракта Shikimori REST API.
AchievementsQuery
Required query for achievements.
ApiError
Структурированная не-2xx ошибка, возвращённая Shikimori API.
AppearRequest
Структура данных публичного контракта Shikimori REST API.
CensoredQuery
Censorship switch used by the calendar route.
ClientConfig
Неизменяемая конфигурация, из которой создаётся ShikimoriClient.
ClientConfigBuilder
Fluent builder для ClientConfig.
ClubInput
Структура данных публичного контракта Shikimori REST API.
CommentPatch
Структура данных публичного контракта Shikimori REST API.
CreateCommentRequest
Структура данных публичного контракта Shikimori REST API.
CreateMessageRequest
Структура данных публичного контракта Shikimori REST API.
CreateReviewRequest
Структура данных публичного контракта Shikimori REST API.
CreateStyleRequest
Структура данных публичного контракта Shikimori REST API.
CreateTopicIgnoreV1Request
Структура данных публичного контракта Shikimori REST API.
CreateTopicRequest
Структура данных публичного контракта Shikimori REST API.
CreateUserRateRequest
Структура данных публичного контракта Shikimori REST API.
CreateVideoRequest
Структура данных публичного контракта Shikimori REST API.
EpisodeNotificationRequest
Структура данных публичного контракта Shikimori REST API.
FavouriteTarget
Структура данных публичного контракта Shikimori REST API.
IsNicknameQuery
Lookup setting for /api/users/:id; nickname lookup is enabled only when true.
LimitQuery
One optional numeric limit.
ListAnimesQuery
List anime query for GET /api/animes and legacy /api/animes/search.
ListClubsQuery
List clubs query.
ListCommentsQuery
List comments query.
ListMangasQuery
List manga query for GET /api/mangas and legacy search.
ListRanobeQuery
List ranobe query for GET /api/ranobe.
ListTopicsQuery
Topic listing query.
ListUserRatesV2Query
User rate list query for v2.
ListUsersQuery
User listing query.
MarkMessagesReadRequest
Структура данных публичного контракта Shikimori REST API.
MessageBulkRequest
Структура данных публичного контракта Shikimori REST API.
MessagePatch
Структура данных публичного контракта Shikimori REST API.
NewComment
Структура данных публичного контракта Shikimori REST API.
NewEpisodeNotification
Структура данных публичного контракта Shikimori REST API.
NewMessage
Структура данных публичного контракта Shikimori REST API.
NewReview
Структура данных публичного контракта Shikimori REST API.
NewStyle
Структура данных публичного контракта Shikimori REST API.
NewTopic
Структура данных публичного контракта Shikimori REST API.
NewUserRate
Структура данных публичного контракта Shikimori REST API.
NewVideo
Структура данных публичного контракта Shikimori REST API.
PageLimit30Query
Query for a related resource with an endpoint-specific page/limit maximum.
PageLimitQuery
A conventional page and limit query.
ReorderFavoriteRequest
Favourite-reorder body.
ReviewPatch
Структура данных публичного контракта Shikimori REST API.
SearchQuery
Generic text search with the optional person-kind filter.
ShikimoriClient
Асинхронный HTTP-клиент Shikimori REST API.
StyleCss
Структура данных публичного контракта Shikimori REST API.
StylePatch
Структура данных публичного контракта Shikimori REST API.
StylePreviewRequest
Структура данных публичного контракта Shikimori REST API.
TopicIgnoreInput
Структура данных публичного контракта Shikimori REST API.
TopicPatch
Структура данных публичного контракта Shikimori REST API.
UpdateClubRequest
Структура данных публичного контракта Shikimori REST API.
UpdateCommentRequest
Структура данных публичного контракта Shikimori REST API.
UpdateMessageRequest
Структура данных публичного контракта Shikimori REST API.
UpdateReviewRequest
Структура данных публичного контракта Shikimori REST API.
UpdateStyleRequest
Структура данных публичного контракта Shikimori REST API.
UpdateTopicRequest
Структура данных публичного контракта Shikimori REST API.
UpdateUserRateRequest
Структура данных публичного контракта Shikimori REST API.
UserAnimeRatesQuery
Query for a user’s anime rate list.
UserHistoryQuery
User history query.
UserImageUpload
Metadata and bytes to upload with POST /api/user_images.
UserMangaRatesQuery
Query for a user’s manga rate list.
UserMessagesQuery
Query for current user’s message folder.
UserRatePatch
Структура данных публичного контракта Shikimori REST API.

Enums§

AgeRating
Строго типизированное input-перечисление Shikimori REST API AgeRating.
AnimeDuration
Строго типизированное input-перечисление Shikimori REST API AnimeDuration.
AnimeKind
Строго типизированное input-перечисление Shikimori REST API AnimeKind.
AnimeOrder
Строго типизированное input-перечисление Shikimori REST API AnimeOrder.
AnimeStatus
Строго типизированное input-перечисление Shikimori REST API AnimeStatus.
BulkMessageKind
Строго типизированное input-перечисление Shikimori REST API BulkMessageKind.
ClubCommentPolicy
Строго типизированное input-перечисление Shikimori REST API ClubCommentPolicy.
ClubImageUploadPolicy
Строго типизированное input-перечисление Shikimori REST API ClubImageUploadPolicy.
ClubTopicPolicy
Строго типизированное input-перечисление Shikimori REST API ClubTopicPolicy.
CommentListTarget
Строго типизированное input-перечисление Shikimori REST API CommentListTarget.
CommentableType
Строго типизированное input-перечисление Shikimori REST API CommentableType.
Error
Ошибка, возвращаемая клиентом.
FavouriteType
Строго типизированное input-перечисление Shikimori REST API FavouriteType.
ListValue
Typed list include/exclude value; Exclude(x) serializes as !x.
MangaKind
Строго типизированное input-перечисление Shikimori REST API MangaKind.
MangaOrder
Строго типизированное input-перечисление Shikimori REST API MangaOrder.
MangaStatus
Строго типизированное input-перечисление Shikimori REST API MangaStatus.
MessageFolder
Строго типизированное input-перечисление Shikimori REST API MessageFolder.
PersonFavouriteKind
Строго типизированное input-перечисление Shikimori REST API PersonFavouriteKind.
PersonKind
Строго типизированное input-перечисление Shikimori REST API PersonKind.
PrivateMessageKind
Строго типизированное input-перечисление Shikimori REST API PrivateMessageKind.
RateTargetType
Строго типизированное input-перечисление Shikimori REST API RateTargetType.
ReviewOpinion
Строго типизированное input-перечисление Shikimori REST API ReviewOpinion.
StyleOwnerType
Строго типизированное input-перечисление Shikimori REST API StyleOwnerType.
TopicForum
Строго типизированное input-перечисление Shikimori REST API TopicForum.
TopicLinkedType
Строго типизированное input-перечисление Shikimori REST API TopicLinkedType.
TopicRootType
Строго типизированное input-перечисление Shikimori REST API TopicRootType.
TopicType
Строго типизированное input-перечисление Shikimori REST API TopicType.
UserRateListType
Resource type used by legacy cleanup/reset user-rate routes.
UserRateStatus
Строго типизированное input-перечисление Shikimori REST API UserRateStatus.
VideoKind
Строго типизированное input-перечисление Shikimori REST API VideoKind.

Traits§

QueryParameters
Internal/public trait used to serialize explicit query DTOs without a URL crate.

Type Aliases§

Result
Стандартный результат всех публичных методов клиента.