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::Json | Response/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§
- Abuse
Request Input - Структура данных публичного контракта Shikimori REST API.
- Achievements
Query - Required query for achievements.
- ApiError
- Структурированная не-2xx ошибка, возвращённая Shikimori API.
- Appear
Request - Структура данных публичного контракта Shikimori REST API.
- Censored
Query - Censorship switch used by the calendar route.
- Client
Config - Неизменяемая конфигурация, из которой создаётся
ShikimoriClient. - Client
Config Builder - Fluent builder для
ClientConfig. - Club
Input - Структура данных публичного контракта Shikimori REST API.
- Comment
Patch - Структура данных публичного контракта Shikimori REST API.
- Create
Comment Request - Структура данных публичного контракта Shikimori REST API.
- Create
Message Request - Структура данных публичного контракта Shikimori REST API.
- Create
Review Request - Структура данных публичного контракта Shikimori REST API.
- Create
Style Request - Структура данных публичного контракта Shikimori REST API.
- Create
Topic Ignore V1Request - Структура данных публичного контракта Shikimori REST API.
- Create
Topic Request - Структура данных публичного контракта Shikimori REST API.
- Create
User Rate Request - Структура данных публичного контракта Shikimori REST API.
- Create
Video Request - Структура данных публичного контракта Shikimori REST API.
- Episode
Notification Request - Структура данных публичного контракта Shikimori REST API.
- Favourite
Target - Структура данных публичного контракта Shikimori REST API.
- IsNickname
Query - Lookup setting for
/api/users/:id; nickname lookup is enabled only when true. - Limit
Query - One optional numeric limit.
- List
Animes Query - List anime query for
GET /api/animesand legacy/api/animes/search. - List
Clubs Query - List clubs query.
- List
Comments Query - List comments query.
- List
Mangas Query - List manga query for
GET /api/mangasand legacy search. - List
Ranobe Query - List ranobe query for
GET /api/ranobe. - List
Topics Query - Topic listing query.
- List
User Rates V2Query - User rate list query for v2.
- List
Users Query - User listing query.
- Mark
Messages Read Request - Структура данных публичного контракта Shikimori REST API.
- Message
Bulk Request - Структура данных публичного контракта Shikimori REST API.
- Message
Patch - Структура данных публичного контракта Shikimori REST API.
- NewComment
- Структура данных публичного контракта Shikimori REST API.
- NewEpisode
Notification - Структура данных публичного контракта Shikimori REST API.
- NewMessage
- Структура данных публичного контракта Shikimori REST API.
- NewReview
- Структура данных публичного контракта Shikimori REST API.
- NewStyle
- Структура данных публичного контракта Shikimori REST API.
- NewTopic
- Структура данных публичного контракта Shikimori REST API.
- NewUser
Rate - Структура данных публичного контракта Shikimori REST API.
- NewVideo
- Структура данных публичного контракта Shikimori REST API.
- Page
Limit30 Query - Query for a related resource with an endpoint-specific page/limit maximum.
- Page
Limit Query - A conventional page and limit query.
- Reorder
Favorite Request - Favourite-reorder body.
- Review
Patch - Структура данных публичного контракта Shikimori REST API.
- Search
Query - Generic text search with the optional person-kind filter.
- Shikimori
Client - Асинхронный HTTP-клиент Shikimori REST API.
- Style
Css - Структура данных публичного контракта Shikimori REST API.
- Style
Patch - Структура данных публичного контракта Shikimori REST API.
- Style
Preview Request - Структура данных публичного контракта Shikimori REST API.
- Topic
Ignore Input - Структура данных публичного контракта Shikimori REST API.
- Topic
Patch - Структура данных публичного контракта Shikimori REST API.
- Update
Club Request - Структура данных публичного контракта Shikimori REST API.
- Update
Comment Request - Структура данных публичного контракта Shikimori REST API.
- Update
Message Request - Структура данных публичного контракта Shikimori REST API.
- Update
Review Request - Структура данных публичного контракта Shikimori REST API.
- Update
Style Request - Структура данных публичного контракта Shikimori REST API.
- Update
Topic Request - Структура данных публичного контракта Shikimori REST API.
- Update
User Rate Request - Структура данных публичного контракта Shikimori REST API.
- User
Anime Rates Query - Query for a user’s anime rate list.
- User
History Query - User history query.
- User
Image Upload - Metadata and bytes to upload with
POST /api/user_images. - User
Manga Rates Query - Query for a user’s manga rate list.
- User
Messages Query - Query for current user’s message folder.
- User
Rate Patch - Структура данных публичного контракта Shikimori REST API.
Enums§
- AgeRating
- Строго типизированное input-перечисление Shikimori REST API
AgeRating. - Anime
Duration - Строго типизированное input-перечисление Shikimori REST API
AnimeDuration. - Anime
Kind - Строго типизированное input-перечисление Shikimori REST API
AnimeKind. - Anime
Order - Строго типизированное input-перечисление Shikimori REST API
AnimeOrder. - Anime
Status - Строго типизированное input-перечисление Shikimori REST API
AnimeStatus. - Bulk
Message Kind - Строго типизированное input-перечисление Shikimori REST API
BulkMessageKind. - Club
Comment Policy - Строго типизированное input-перечисление Shikimori REST API
ClubCommentPolicy. - Club
Image Upload Policy - Строго типизированное input-перечисление Shikimori REST API
ClubImageUploadPolicy. - Club
Topic Policy - Строго типизированное input-перечисление Shikimori REST API
ClubTopicPolicy. - Comment
List Target - Строго типизированное input-перечисление Shikimori REST API
CommentListTarget. - Commentable
Type - Строго типизированное input-перечисление Shikimori REST API
CommentableType. - Error
- Ошибка, возвращаемая клиентом.
- Favourite
Type - Строго типизированное input-перечисление Shikimori REST API
FavouriteType. - List
Value - Typed list include/exclude value;
Exclude(x)serializes as!x. - Manga
Kind - Строго типизированное input-перечисление Shikimori REST API
MangaKind. - Manga
Order - Строго типизированное input-перечисление Shikimori REST API
MangaOrder. - Manga
Status - Строго типизированное input-перечисление Shikimori REST API
MangaStatus. - Message
Folder - Строго типизированное input-перечисление Shikimori REST API
MessageFolder. - Person
Favourite Kind - Строго типизированное input-перечисление Shikimori REST API
PersonFavouriteKind. - Person
Kind - Строго типизированное input-перечисление Shikimori REST API
PersonKind. - Private
Message Kind - Строго типизированное input-перечисление Shikimori REST API
PrivateMessageKind. - Rate
Target Type - Строго типизированное input-перечисление Shikimori REST API
RateTargetType. - Review
Opinion - Строго типизированное input-перечисление Shikimori REST API
ReviewOpinion. - Style
Owner Type - Строго типизированное input-перечисление Shikimori REST API
StyleOwnerType. - Topic
Forum - Строго типизированное input-перечисление Shikimori REST API
TopicForum. - Topic
Linked Type - Строго типизированное input-перечисление Shikimori REST API
TopicLinkedType. - Topic
Root Type - Строго типизированное input-перечисление Shikimori REST API
TopicRootType. - Topic
Type - Строго типизированное input-перечисление Shikimori REST API
TopicType. - User
Rate List Type - Resource type used by legacy cleanup/reset user-rate routes.
- User
Rate Status - Строго типизированное input-перечисление Shikimori REST API
UserRateStatus. - Video
Kind - Строго типизированное input-перечисление Shikimori REST API
VideoKind.
Traits§
- Query
Parameters - Internal/public trait used to serialize explicit query DTOs without a URL crate.
Type Aliases§
- Result
- Стандартный результат всех публичных методов клиента.