Home

Awesome

Reactive Jikan

Maven Central GitHub Workflow Codecov

A fast and fully-typed API wrapper for the Jikan API V4, with the power of Project Reactor and reactive streams.

Supported versions

API versionreactive-jikan version
V31.1.0
V42.2.0

Installation

Add the following dependency to your build file.

If using Gradle (build.gradle):

dependencies {
    implementation 'net.sandrohc:reactive-jikan:2.2.0'
}

If using Maven (pom.xml):

<dependency>
    <groupId>net.sandrohc</groupId>
    <artifactId>reactive-jikan</artifactId>
    <version>2.2.0</version>
</dependency>

If you want to use development versions, see: https://jitpack.io/#net.sandrohc/reactive-jikan

Usage

The Reactive Jikan library provides all queries through the Query classes. Once the desired query is created (the QueryFactory can be used to help you navigate through all the available queries), it can be passed to the Jikan instance. Some queries have optional parameters, like the search queries; for more details, please see the javadocs for each query or refer to the official Jikan API documentation.

After the query has been configured with the desired parameters, it can be executed by calling query.execute() (or alternatively jikan.query(yourQuery)). The value returned is a reactive stream of type Mono<T> or Flux<T> depending on the query. The HTTP request is only made once the methods subscribe() or block() are called. For more information on reactive queries, please read the relevant documentation.

Here are some examples on how to use this library:

// Create the Jikan instance with default parameters.
// You can also use the builder, JikanBuilder, to specify custom parameters.
Jikan jikan = new Jikan(); 

// Fetch the anime with ID 1. Returns a single value, a mono.
Anime anime = jikan.query().anime().get(1)
        .execute()
        .block();

// Search for 'sword art online'. Returns a list of values, a flux.
Collection<Anime> results = jikan.query().anime().search()
		.query("sword art online")
		.limit(5)
		.status(AnimeStatus.AIRING)
		.orderBy(AnimeOrderBy.MEMBERS, SortOrder.ASCENDING)
		.execute()
		.collectList()
		.block();

Android

The following changes are necessary to use this library on Android.

Jikan jikan = new Jikan.JikanBuilder()
        .httpClientCustomizer(httpClient -> httpClient.resolver(DefaultAddressResolverGroup.INSTANCE))
        .build();

Caching

Caching comes disabled by default. To enable it, please provide an implementation of JikanCache to the Jikan instance.

The following is an example using Caffeine as the cache library. Beware that Caffeine is not supported in Android!

// build.gradle
dependencies {
	implementation 'com.github.ben-manes.caffeine:caffeine:2.9.3'
}

// App.java
JikanCache jikanCache = new JikanCache() {
    protected final Cache<String, JikanValueHolder> cache = Caffeine.newBuilder().maximumSize(10_000).expireAfter(new JikanExpiry()).build();

    public void put(String key, Object value, OffsetDateTime expires) {
        cache.put(key, new JikanValueHolder(value, expires));
    }

    public Optional<Object> get(String key) {
        return Optional.ofNullable(cache.getIfPresent(key)).map(holder -> holder.value);
    }

    class JikanValueHolder {
        public final Object value;
        public final long expireTime;

        public JikanValueHolder(Object value, OffsetDateTime expires) {
            this.value = value;
            this.expireTime = TimeUnit.SECONDS.toNanos(expires.toEpochSecond());
        }
    }

    class JikanExpiry implements Expiry<String, JikanValueHolder> {
        public long expireAfterCreate(String key, JikanValueHolder value, long currentTime) {
            return value.expireTime;
        }

        public long expireAfterUpdate(String key, JikanValueHolder value, long currentTime, long currentDuration) {
            return currentDuration; // Do not modify expire date
        }

        public long expireAfterRead(String key, JikanValueHolder value, long currentTime, long currentDuration) {
            return currentDuration; // Do not modify expire date
        }
    }
};

Jikan jikan = new Jikan.JikanBuilder()
        .cache(jikanCache)
        .build();

Endpoints

The following is an exhaustive list of all the endpoints and query classes supported by the Reactive Jikan library.

EndpointQueryResult
Anime
/{id}AnimeQueryAnime
/{id}/characters_staffAnimeCharactersAndStaffQueryAnimeCharactersAndStaff
/{id}/episodes/{page}AnimeEpisodesQueryAnimeEpisodes
/{id}/newsAnimeNewsQueryAnimeNews
/{id}/picturesAnimePicturesQuery(list) AnimePicture
/{id}/videosAnimeVideosQueryAnimeVideos
/{id}/statisticsAnimeStatisticsQueryStats
/{id}/forumAnimeForumQuery(list) ForumTopic
/{id}/moreinfoAnimeMoreInfoQueryMoreInfo
/{id}/reviews/{page}AnimeReviewsQuery(list) Review
/{id}/recommendationsAnimeRecommendationsQuery(list) Recommendation
/{id}/userupdates/{page}AnimeUserUpdatesQuery(list) UserUpdate
Manga
/{id}MangaQueryManga
/{id}/charactersMangaCharactersQuery(list) RoleSubEntity
/{id}/newsMangaNewsQuery(list) NewsArticle
/{id}/picturesMangaPicturesQuery(list) Pictures
/{id}/statisticsMangaStatisticsQueryStats
/{id}/forumMangaForumQuery(list) ForumTopic
/{id}/moreinfoMangaMoreInfoQueryMoreInfo
/{id}/reviews/{page}MangaReviewsQuery(list) Review
/{id}/recommendationsMangaRecommendationsQueryRecommendations
/{id}/userupdates/{page}MangaUserUpdatesQuery(list) UserUpdate
Person
/{id}PersonQueryPerson
/{id}/picturesPersonPicturesQuery(list) Picture
Character
/{id}CharacterQueryCharacter
/{id}/picturesCharacterPicturesQuery(list) Picture
Search
/animeAnimeSearchQuery(list) AnimeSearchSub
/mangaMangaSearchQuery(list) MangaSearchSub
/personPersonSearchQuery(list) PersonSearchSub
/characterCharacterSearchQuery(list) CharacterSearchSub
Season
/{year}/{season}SeasonQuery(list) SeasonAnime
/archiveSeasonArchiveQuery(list) SeasonArchiveYear
/laterSeasonLaterQuery(list) SeasonAnime
Schedule
/{day}ScheduleQuerySchedule
Top
/anime/{page}/{subtype}AnimeTopQuery(list) AnimeTopSub
/manga/{page}/{subtype}MangaTopQuery(list) MangaTopSub
Genre
/anime/{page}/{subtype}AnimeGenreQuery(list) AnimeGenreSub
/manga/{page}/{subtype}MangaGenreQuery(list) MangaGenreSub
Producer
/{id}/{page}ProducerQueryProducer
Magazine
/{id}/{page}MagazineQueryMagazine
User
/{username}UserProfileQueryUserProfile
/{username}/history(not implemented)
/{username}/history/animeUserHistoryAnimeQuery(list) UserHistory
/{username}/history/mangaUserHistoryAnimeQuery(list) UserHistory
/{username}/friends/{page}UserFriendsQuery(list) UserFriend
/{username}/animelist/{status}UserAnimeQuery(list) UserAnime
/{username}/mangalist/{status}UserMangaQuery(list) UserManga
Club
/{id}ClubQueryClub
/{id}/members/{page}ClubMembersQuery(list) ClubMember
Meta
/status(not implemented)
/requests/{type}/{period}/{page}(not implemented)