Merge pull request #36 from Lycoon/dev

Deploy version 5.1.0

README.md

@@ -1,59 +1,96 @@
 ![ClashAPI logo](/src/main/resources/logo.png)
 
 <p align="center">
-  <a href="https://github.com/Lycoon/clash-api/actions/workflows/check-ci.yml">
-    <img alt="Check CI status" src="https://github.com/Lycoon/clash-api/actions/workflows/check-ci.yml/badge.svg?branch=dev">
-  </a>
-  <img alt="GitHub code size in bytes" src="https://img.shields.io/github/languages/code-size/Lycoon/clash-api">
+    <img alt="GitHub License" src="https://img.shields.io/github/license/Lycoon/clash-api">
+    <img alt="Maven Central" src="https://img.shields.io/maven-central/v/io.github.lycoon/clash-api">
+    <img alt="Static Badge" src="https://img.shields.io/badge/Java%20version-8%2B-blue">
 </p>
 
-ClashAPI is a very simple yet very complete Kotlin wrapper for the Clash of Clans mobile game API. 
-It allows developers to easily do requests to the game API without bothering about JSON and HTTP handling.
-It is intended to be lightweight and as intuitive as possible to use.
+<p align="center">
+    <b>ClashAPI</b> is a very simple yet very complete JVM wrapper for the <i>Clash of Clans</i> mobile game API
+</p>
 
-## How does it work?
-I analyzed JSON responses from the Clash of Clans API to recreate the models as Java structures so you don't have to deal with deserialization and data categorization each time. You can therefore simply access game data through your Java/Kotlin (JVM) classes and methods, all documented!
+It allows developers to easily access the game API with their favorite language without bothering 
+about JSON and HTTP handling. It is intended to be lightweight and as intuitive as possible to use.
+It can be imported in any JVM project, with guaranteed compatibility with Java and Kotlin.
 
-## Setup
-ClashAPI is available on Maven Central. You can add it to your project using Maven or Gradle.
+# How does it work?
+I read through the documentation of Clash of Clans API to recreate the models as data structures so you don't have to
+deal with JSON de/serialization and data categorization each time. You can therefore simply access game data through 
+your Java/Kotlin (JVM) classes and methods, all well documented!
 
-### Maven
+## Maven
 Inside your `<dependencies>` scope of your `pom.xml` file, add the following:
 ```xml
 <dependency>
     <groupId>io.github.lycoon</groupId>
     <artifactId>clash-api</artifactId>
-    <version>5.0.0</version>
+    <version>5.1.0</version>
 </dependency>
 ```
 
-### Gradle
+## Gradle
 Inside your `dependencies` scope of your `build.gradle` file, add the following:
 ```gradle
-implementation 'io.github.lycoon:clash-api:5.0.0'
+implementation 'io.github.lycoon:clash-api:5.1.0'
 ```
 
-## Quick start
+# Quick start
+## 1. Authenticating
+Initializing a ClashAPI instance is very simple. There are two ways of authenticating to the Clash of Clans API:
+either by providing your token(s) directly (which you must have generated prior), or your API developer email/password
+credentials (which will generate them for you).
+
+### Token method (recommended)
+Instancing with token(s) is the safest way to go as in case of a leak, you would just need to revoke the concerned 
+key from your developer account. The downside is that your token is linked to a single IP address. In case you
+don't know the IP address on which your code will run (e.g. if you are using a cloud service), or if you just
+don't want the hassle of updating your token each time your IP changes, you can go with the 'Credentials' way.
+
 ```java
-// 1. Create an instance of ClashAPI by providing your Clash of Clans API token to the constructor
+// Single token
 ClashAPI clashAPI = new ClashAPI("token");
+```
 
-// 2. And do the requests you need. Yes, it's as simple :)
-Player player = clashAPI.getPlayer("#AAAA00");
+This second constructor allows you to provide a list of tokens, which enables you to bypass rate limitations
+as the library will cycle through all of them for each request.
+```java
+// Token list
+ArrayList<String> tokens;
 
+tokens = listOf("tokenA", "tokenB", "tokenC");        // (Kotlin)
+tokens = Arrays.asList("tokenA", "tokenB", "tokenC"); // (Java)
+
+ClashAPI clashAPI = new ClashAPI(tokens);
+```
+
+### Credentials method
+This method is the simplest but not the safest as in the case of a leak, your credentials would be exposed.
+Authenticating with your credentials enables dynamic IP support if you cannot know the IP on which your code will run.
+```java
+// Developer API credentials
+ClashAPI clashAPI = new ClashAPI("email", "password");
+```
+
+## 2. Making requests
+```java
+// Yes, it's as simple :)
+Player player = clashAPI.getPlayer("#AAAA00");
 int townhallLevel = player.getTownHallLevel();
-String clanRole = player.getRole();
+Role clanRole = player.getRole();
 List<Troop> heroes = player.getHeroes();
-...
+// ...
 ```
 
-## What's the token?
-In order to make calls to the Clash of Clans API, Supercell (developer of the game) asks you to sign up on [this website](https://developer.clashofclans.com/#/register). Then, head to your [profile](https://developer.clashofclans.com/#/account) and create a new key. Once you are done, the key will generate the token. Copy it and provide it to the `ClashAPI` constructor.
-
-Though this token is linked to the IP address you gave, I would advise **not to hardcode it** inside your code, for safety sake. Paste it in a separate file that you would access from your code. It will prevent your token being spread if you ever share your files.
+# What's a token?
+In order to make calls to the Clash of Clans API, Supercell (the game developer) requires to provide a token for each
+request. You can get a token by signing up on the [developer portal](https://developer.clashofclans.com/#/register). Then, head to your [profile](https://developer.clashofclans.com/#/account) and create 
+a new key providing IP addresses you want to allow. Once you are done, the key will generate the token. 
+You can now copy it and provide it to the `ClashAPI` constructor.
 
-## Report bugs
-You've found a bug? Let me know by opening an issue. 
+Though this token is tied to the IP addresses you provided, I would advise **not to hardcode it** inside your code, 
+for safety sake. Paste it in a separate file that you would access from your code. It will prevent your token 
+being spread if you ever share your files mistakenly. The same goes for the credentials method.
 
-## Disclaimer
+# Disclaimer
 *This material is unofficial and is not endorsed by Supercell. For more information see Supercell's Fan Content Policy: www.supercell.com/fan-content-policy.*

pom.xml

@@ -5,7 +5,7 @@
 
   <groupId>io.github.lycoon</groupId>
   <artifactId>clash-api</artifactId>
-  <version>5.0.0</version>
+  <version>5.1.0</version>
 
   <!-- Project metadata -->
   <name>${project.groupId}:${project.artifactId}</name>
@@ -62,7 +62,7 @@
     <dependency>
       <groupId>com.squareup.okhttp3</groupId>
       <artifactId>okhttp</artifactId>
-      <version>4.10.0</version>
+      <version>5.0.0-alpha.11</version>
     </dependency>
 
     <dependency>
@@ -72,7 +72,6 @@
     </dependency>
   </dependencies>
 
-
   <build>
     <plugins>
       <!-- Maven Source plugin -->