P.E.K.K.A - Clash Royale API (official) and Royale API (unofficial) Client Library for .NET

P.E.K.K.A is a client library (C# wrapper) targeting .NET Standard 2.0 and .NET 4.6.1 that provides an easy way to interact with both official Clash Royale API and unofficial public API Royale API

All API requests must be accompanied by a developer key. You need to register then create a key for Clash Royale API (official) on Clash Royale API Website. You can learn how to obtain and manage your developer key for Royale API (unofficial) on Royale API Website.

	Stable	Nightly
Clash Royale API Client
Royale API Client

Supported Platforms

• .NET 4.6.1 (Desktop / Server)
• .NET Standard 2.0

Features

• Dependency injection friendly (can also be used standalone, see below)
• Supports async and sync (via extension method, see below) calls.

Continuous integration

Client Library	Platform	Build Server	Build Status	Integration Tests
Clash Royale API Client	Windows	Azure Pipelines
Clash Royale API Client	Ubuntu	Azure Pipelines
Clash Royale API Client	MacOS	Azure Pipelines
Royale API Client	Windows	Azure Pipelines
Royale API Client	Ubuntu	Azure Pipelines
Royale API Client	MacOS	Azure Pipelines
All	Windows	AppVeyor

Table of Contents

1. Installation
2. Usage
   • Standalone Initialization
     • Royale Api
     • Clash Royale Api
   • Microsoft.Extensions.DependencyInjection Initialization
     • Royale Api
     • Clash Royale Api
   • Call Endpoints
   • Synchronous Wrapper
3. License

Installation

	Logo	Stable	Nightly
P.E.K.K.A Clash Royale API (official)
P.E.K.K.A Royale API (unofficial)

Following commands can be used to install both Pekka.ClashRoyaleApi.Client and Pekka.RoyaleApi.Client, run the following command in the Package Manager Console

Install-Package Pekka.ClashRoyaleApi.Client
Install-Package Pekka.RoyaleApi.Client

Or use dotnet cli

dotnet Pekka.ClashRoyaleApi.Client
dotnet Pekka.RoyaleApi.Client

Usage

The usage of both Pekka.ClashRoyaleApi.Client and Pekka.RoyaleApi.Client libraries are similar. And both can be used with any DI library, or it can be used standalone.

Standalone Initialization

If you do not want to use any DI framework, you have to instantiate ClashRoyaleApiStandalone or RoyaleApiStandalone as follows.

RoyaleApiStandalone Usage

ApiOptions apiOptions = new ApiOptions("<your token>", "https://api.royaleapi.com/");
var apiClientContext = RoyaleApiStandalone.Create(apiOptions);
IPlayerClient playerClient = apiClientContext.PlayerClient;
IClanClient clanClient = apiClientContext.ClanClient;
IVersionClient clanClient = apiClientContext.VersionClient;

ClashRoyaleApiStandalone Usage

ApiOptions apiOptions = new ApiOptions("<your token>", "https://api.clashroyale.com/v1/");
var apiClientContext = ClashRoyaleApiStandalone.Create(apiOptions);
IPlayerClient playerClient = apiClientContext.PlayerClient;
IClanClient clanClient = apiClientContext.ClanClient;
ITournamentClient tournamentClient = apiClientContext.TournamentClient;
ICardClient cardClient = apiClientContext.CardClient;
ILocationClient locationClient = apiClientContext.LocationClient;

apiClientContext contains all necessary clients.

Microsoft.Extensions.DependencyInjection Initialization

First, you need to install Microsoft.Extensions.DependencyInjection and Microsoft.Extensions.Http NuGet package as follows

dotnet add package Microsoft.Extensions.DependencyInjection
dotnet add package Microsoft.Extensions.Http

By installing Microsoft.Extensions.Http you will be able to use HttpClientFactory.In the words of the ASP.NET Team it is “an opinionated factory for creating HttpClient instances” and is a new feature comes with the release of ASP.NET Core 2.1.

If you don't want to use HttpClientFactory, you must register HttpClient yourself with the container.

Clash Royale Api

Register necessary dependencies to ServiceCollection as follows

ApiOptions apiOptions = new ApiOptions("<your token>", "https://api.clashroyale.com/v1/");

var services = new ServiceCollection();

services.AddSingleton(apiOptions);
services.AddHttpClient<IRestApiClient, RestApiClient>((provider, client) =>
{
    var options = provider.GetRequiredService<ApiOptions>();
    client.BaseAddress = new Uri(options.BaseUrl);
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", options.BearerToken);
});

services.AddTransient<IPlayerClient, PlayerClient>();
services.AddTransient<IClanClient, ClanClient>();
services.AddTransient<ITournamentClient, TournamentClient>();
services.AddTransient<ICardClient, CardClient>();
services.AddTransient<ILocationClient, LocationClient>();
services.AddTransient<IGlobalTournamentClient, GlobalTournamentClient>();

ServiceProvider buildServiceProvider = services.BuildServiceProvider();

var playerClient = buildServiceProvider.GetRequiredService<IPlayerClient>();
var clanClient = buildServiceProvider.GetRequiredService<IClanClient>();
var tournamentClient = buildServiceProvider.GetRequiredService<ITournamentClient>();
var cardClient = buildServiceProvider.GetRequiredService<ICardClient>();
var locationClient = buildServiceProvider.GetRequiredService<ILocationClient>();
var globalTournamentClient = buildServiceProvider.GetRequiredService<IGlobalTournamentClient>();

See sandbox project for more examples.

Royale Api

Register necessary dependencies to ServiceCollection as follows

ApiOptions apiOptions = new ApiOptions("<your token>", "https://api.royaleapi.com/");

var services = new ServiceCollection();

services.AddSingleton(apiOptions);
services.AddHttpClient<IRestApiClient, RestApiClient>((provider, client) =>
{
    var options = provider.GetRequiredService<ApiOptions>();
    client.BaseAddress = new Uri(options.BaseUrl);
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", options.BearerToken);
});
services.AddTransient<IPlayerClient, PlayerClient>();
services.AddTransient<IClanClient, ClanClient>();
services.AddTransient<IVersionClient, VersionClient>();
services.AddTransient<IConstantClient, ConstantClient>();

var buildServiceProvider = services.BuildServiceProvider();

var playerClient = buildServiceProvider.GetRequiredService<IPlayerClient>();
var clanClient = buildServiceProvider.GetRequiredService<IClanClient>();
var versionClient = buildServiceProvider.GetRequiredService<IVersionClient>();
var constantClient = buildServiceProvider.GetRequiredService<IConstantClient>();
var restApiClient = buildServiceProvider.GetRequiredService<IRestApiClient>();

See sandbox project for more examples.

Call Endpoints

There are two ways to call an endpoint. The only difference is the return types. The methods that end with ResponseAsync returns ApiResponse<TModel> which contains model itself, HTTP status codes, error message and response headers.

ApiResponse<Player> playerResponse = await playerClient.GetPlayerResponseAsync(playerTag);

if(playerResponse.Error)
{
  HttpStatusCode statusCode = playerResponse.HttpStatusCode;
  string errorMessage = playerResponse.Message;
  IDictionary<string, string> headers = playerResponse.Headers;
  string urlPath = playerResponse.UrlPath;
    // Handle http error
}

Player player = playerResponse.Model;

The methods that end with Async returns model itself without additional HTTP response information. But in the case of HTTP error, you need to handle exceptions.

Player player = await playerClient.GetPlayerAsync(playerTag);

Synchronous Wrapper

For synchronous calls, Task extension method RunSync can be used.

var player = playerClient.GetPlayerResponseAsync(playerTag).RunSync();

But there is a possibility that this extension method can't cover all cases. See Stackoverflow article

License

Licensed under MIT, see LICENSE for the full text.