jcrapi2 4.0.8

A Java Wrapper For Official Supercell Clash Royal Api

Why we don't use the Swagger scheme?

A big sorry for that, but the quality of that scheme changes from day to day. Another big sorry, but the OpenApi Java generator is producing code quality we like much. That's simple why :) If you think the same way (it may differ from case to case of course), feel free to continue using our wrapper.

Why we moved to the amazing services of packagecloud?

We moved to packagecloud.io because the bintray closed their nice hosting... And packagecloud.io is a really nice place to be :)

Join us on Discord

https://discord.gg/WNb5c8hn

Simplest Usage

Note: Please combine the builder methods as it makes sense. The demonstrated is showing only all possibilities. For more information please check

https://developer.clashroyale.com/#/documentation

Use one of these endpoints:

Official endpoint

    https://api.clashroyale.com/v1

Proxy endpoint

    https://crproxy.royaleapi.dev/v1

Bind essentials to your project

<repositories>
    <repository>
        <id>packagecloud-supercell-api-wrapper-essentials</id>
        <url>https://packagecloud.io/mlieshoff/supercell-api-wrapper-essentials/maven2</url>
        <releases>
            <enabled>true</enabled>
        </releases>
        <snapshots>
            <enabled>true</enabled>
        </snapshots>
    </repository>
</repositories>

and use the dependency

<dependency>
    <groupId>supercell-api-wrapper-essentials</groupId>
    <artifactId>supercell-api-wrapper-essentials</artifactId>
    <version>1.0.1</version>
</dependency>

Use built-in standard connector

Connector connector = new StandardConnector();

or use the new filesystem cached connector

Connector connector = new FilesystemCachedConnector("jcrapi2")

or use custom implementation

    Connector connector = new Connector() {
        @Override
        public <T extends IResponse> T get(RequestContext requestContext) throws ConnectorException {
                // do not forget to use auth header with *Bearer*
                String authHeader =  "Authorization: Bearer " + requestContext.getApiKey();
            }
        }
    );

connect to the api with creating a ClashRoyale instance.

    JCrApi jCrApi = new JCrApi("https://crproxy.royaleapi.dev/v1", "my-api-key", connector);

list all supported apis

    System.out.println(jCrApi.listApis());

List of APIs and example usages

ClanApi

    // create an instance for the api
    ClanApi api = jCrApi.getApi(ClanApi.class);

    // findAll
    ClansResponse response = api.findAll(clansRequest.builder()
           .name()
           .locationId()
           .minMembers()
           .maxMembers()
           // pagination
           .limit()
           .after()
           .before()
           // store raw response
           .storeRawResponse()
        .build()
    ).get();

    // findByTag
    ClanResponse response = api.findByTag(clanRequest.builder()
           .clanTag()
           // store raw response
           .storeRawResponse()
        .build()
    ).get();

    // getRiverRaceLog
    RiverRaceLogResponse response = api.getRiverRaceLog(riverRaceLogRequest.builder()
           .clanTag()
           // pagination
           .limit()
           .after()
           .before()
           // store raw response
           .storeRawResponse()
        .build()
    ).get();

    // getMembers
    ClanMembersResponse response = api.getMembers(clanMembersRequest.builder()
           .clanTag()
           // pagination
           .limit()
           .after()
           .before()
           // store raw response
           .storeRawResponse()
        .build()
    ).get();

    // getCurrentRiverRace
    CurrentRiverRaceResponse response = api.getCurrentRiverRace(currentRiverRaceRequest.builder()
           .clanTag()
           // store raw response
           .storeRawResponse()
        .build()
    ).get();

PlayerApi

    // create an instance for the api
    PlayerApi api = jCrApi.getApi(PlayerApi.class);

    // findByTag
    PlayerResponse response = api.findByTag(playerRequest.builder()
           .playerTag()
           // store raw response
           .storeRawResponse()
        .build()
    ).get();

    // getUpcomingChests
    UpcomingChestsResponse response = api.getUpcomingChests(upcomingChestsRequest.builder()
           .playerTag()
           // store raw response
           .storeRawResponse()
        .build()
    ).get();

    // getBattleLog
    BattleLogResponse response = api.getBattleLog(battleLogRequest.builder()
           .playerTag()
           // store raw response
           .storeRawResponse()
        .build()
    ).get();

CardApi

    // create an instance for the api
    CardApi api = jCrApi.getApi(CardApi.class);

    // findAll
    CardsResponse response = api.findAll(cardsRequest.builder()
           // store raw response
           .storeRawResponse()
        .build()
    ).get();

TournamentApi

    // create an instance for the api
    TournamentApi api = jCrApi.getApi(TournamentApi.class);

    // findAll
    TournamentsResponse response = api.findAll(tournamentsRequest.builder()
           .name()
           // pagination
           .limit()
           .after()
           .before()
           // store raw response
           .storeRawResponse()
        .build()
    ).get();

    // findByTag
    TournamentResponse response = api.findByTag(tournamentRequest.builder()
           .tournamentTag()
           // pagination
           .limit()
           .after()
           .before()
           // store raw response
           .storeRawResponse()
        .build()
    ).get();

LocationApi

    // create an instance for the api
    LocationApi api = jCrApi.getApi(LocationApi.class);

    // findAll
    LocationsResponse response = api.findAll(locationsRequest.builder()
           // pagination
           .limit()
           .after()
           .before()
           // store raw response
           .storeRawResponse()
        .build()
    ).get();

    // findById
    LocationResponse response = api.findById(locationRequest.builder()
           .locationId()
           // store raw response
           .storeRawResponse()
        .build()
    ).get();

    // getClanRankings
    ClanRankingsResponse response = api.getClanRankings(clanRankingsRequest.builder()
           .locationId()
           // pagination
           .limit()
           .after()
           .before()
           // store raw response
           .storeRawResponse()
        .build()
    ).get();

    // getPlayerRankings
    PlayerRankingsResponse response = api.getPlayerRankings(playerRankingsRequest.builder()
           .locationId()
           // pagination
           .limit()
           .after()
           .before()
           // store raw response
           .storeRawResponse()
        .build()
    ).get();

    // getClanWarRankings
    ClanWarRankingsResponse response = api.getClanWarRankings(clanWarRankingsRequest.builder()
           .locationId()
           // pagination
           .limit()
           .after()
           .before()
           // store raw response
           .storeRawResponse()
        .build()
    ).get();

    // getTopPlayerLeagueSeasons
    TopPlayerLeagueSeasonsResponse response = api.getTopPlayerLeagueSeasons(topPlayerLeagueSeasonsRequest.builder()
           // pagination
           .limit()
           .after()
           .before()
           // store raw response
           .storeRawResponse()
        .build()
    ).get();

    // getTopPlayerLeagueSeason
    TopPlayerLeagueSeasonResponse response = api.getTopPlayerLeagueSeason(topPlayerLeagueSeasonRequest.builder()
           .seasonId()
           // store raw response
           .storeRawResponse()
        .build()
    ).get();

    // getTopPlayerLeagueSeasonRankings
    TopPlayerLeagueSeasonRankingsResponse response = api.getTopPlayerLeagueSeasonRankings(topPlayerLeagueSeasonRankingsRequest.builder()
           .seasonId()
           // pagination
           .limit()
           .after()
           .before()
           // store raw response
           .storeRawResponse()
        .build()
    ).get();

    // getTopPlayerPathOfLegendSeasonRankings
    TopPlayerPathOfLegendSeasonRankingsResponse response = api.getTopPlayerPathOfLegendSeasonRankings(topPlayerPathOfLegendSeasonRankingsRequest.builder()
           .seasonId()
           // pagination
           .limit()
           .after()
           .before()
           // store raw response
           .storeRawResponse()
        .build()
    ).get();

    // getTopPlayerPathOfLegendRankings
    TopPlayerPathOfLegendRankingsResponse response = api.getTopPlayerPathOfLegendRankings(topPlayerPathOfLegendRankingsRequest.builder()
           .locationId()
           // pagination
           .limit()
           .after()
           .before()
           // store raw response
           .storeRawResponse()
        .build()
    ).get();

    // getTopPlayerTournamentRankings
    TopPlayerTournamentRankingsResponse response = api.getTopPlayerTournamentRankings(topPlayerTournamentRankingsRequest.builder()
           .tournamentTag()
           // pagination
           .limit()
           .after()
           .before()
           // store raw response
           .storeRawResponse()
        .build()
    ).get();

    // getTopPlayerLeagueSeasonsV2
    TopPlayerLeagueSeasonsV2Response response = api.getTopPlayerLeagueSeasonsV2(topPlayerLeagueSeasonsV2Request.builder()
           // pagination
           .limit()
           .after()
           .before()
           // store raw response
           .storeRawResponse()
        .build()
    ).get();

ChallengeApi

    // create an instance for the api
    ChallengeApi api = jCrApi.getApi(ChallengeApi.class);

    // findAll
    ChallengesResponse response = api.findAll(challengesRequest.builder()
           // store raw response
           .storeRawResponse()
        .build()
    ).get();

GlobalTournamentApi

    // create an instance for the api
    GlobalTournamentApi api = jCrApi.getApi(GlobalTournamentApi.class);

    // findAll
    GlobalTournamentsResponse response = api.findAll(globalTournamentsRequest.builder()
           // pagination
           .limit()
           .after()
           .before()
           // store raw response
           .storeRawResponse()
        .build()
    ).get();

LeaderboardApi

    // create an instance for the api
    LeaderboardApi api = jCrApi.getApi(LeaderboardApi.class);

    // findAll
    LeaderboardsResponse response = api.findAll(leaderboardsRequest.builder()
           // pagination
           .limit()
           .after()
           .before()
           // store raw response
           .storeRawResponse()
        .build()
    ).get();

    // findById
    LeaderboardResponse response = api.findById(leaderboardRequest.builder()
           .leaderboardId()
           // pagination
           .limit()
           .after()
           .before()
           // store raw response
           .storeRawResponse()
        .build()
    ).get();

Add or replace registered API's

    JCrApi jCrApi = new JCrApi(...);
    jCrApi.register(MyApi.class, MyApiImpl.class.getName());
    MyApi myApi = jCrApi.getApi(MyApi.class);
    GoodiesResponse goodiesResponse = myApi.findAllGoodies(new GoodiesRequest(...))).get();

Custom API implementations just need to inherit from BaseApi.

Asynchronous usage

All requests are returning java.concurrent.Future. The execution will be asynchronous by default.

How to bind the packagecloud repository

    <repositories>
        <repository>
            <id>packagecloud-jcrapi2</id>
            <url>https://packagecloud.io/mlieshoff/jcrapi2/maven2</url>
            <releases>
                <enabled>true</enabled>
            </releases>
            <snapshots>
                <enabled>true</enabled>
            </snapshots>
        </repository>
    </repositories>

Add dependency

to Gradle:

    implementation group: 'jcrapi2', name: 'jcrapi2', version: '4.0.8'

to Maven:

    <dependency>
        <groupId>jcrapi2</groupId>
        <artifactId>jcrapi2</artifactId>
        <version>4.0.8</version>
    </dependency>

Continuous Integration

https://github.com/mlieshoff/jcrapi2/actions

Repository

https://packagecloud.io/mlieshoff/jcrapi2

Logging

We are using SLF4j.

Usage of RoyaleApi proxy

This wrapper can be easyly connected to the proxy of our friends on RoyaleAPI. Please proceed first the steps described here:

https://docs.royaleapi.com/#/proxy

Then initialize an instance of class Api like that:

    JCrApi jCrApi = new JCrApi("https://crproxy.royaleapi.dev/v1", API_KEY, CONNECTOR);

That's all, enjoy :)

Library updates

Minor versions

mvn versions:update-parent versions:use-latest-releases versions:update-properties versions:commit -DallowMajorUpdates=false

Major versions

mvn versions:update-parent versions:use-latest-releases versions:update-properties versions:commit -DallowMajorUpdates=true

Update plugins

mvn versions:display-plugin-updates -U

Contributing

1. Feel free to open Pull Requests with your ideas :)