From 74b1b587a6972319be2860f67870d6688aefd18b Mon Sep 17 00:00:00 2001
From: HardiReady <hardi@noarch.de>
Date: Sat, 31 Mar 2018 19:23:49 +0200
Subject: [PATCH] add api docs for player endpoints

---
 api/apib/army-management/awardings.apib |  2 +-
 api/apib/data_structures/_player.apib   | 34 +++++++++++++++++++++++++
 api/apib/data_structures/_user.apib     |  2 +-
 api/apib/data_structures/_war.apib      |  2 +-
 api/apib/data_structures/index.apib     |  2 ++
 api/apib/dev-doc.apib                   |  2 ++
 api/apib/statistics/players.apib        | 34 +++++++++++++++++++++++++
 7 files changed, 75 insertions(+), 3 deletions(-)
 create mode 100644 api/apib/data_structures/_player.apib
 create mode 100644 api/apib/statistics/players.apib

diff --git a/api/apib/army-management/awardings.apib b/api/apib/army-management/awardings.apib
index d1fb314..6549f22 100644
--- a/api/apib/army-management/awardings.apib
+++ b/api/apib/army-management/awardings.apib
@@ -1,4 +1,4 @@
-### GET Awardings [GET /awardings{?userId,inProgress,fractFilter}]
+### Get Awardings [GET /awardings{?userId,inProgress,fractFilter}]
 
 List all awardings
 
diff --git a/api/apib/data_structures/_player.apib b/api/apib/data_structures/_player.apib
new file mode 100644
index 0000000..c6404d1
--- /dev/null
+++ b/api/apib/data_structures/_player.apib
@@ -0,0 +1,34 @@
+# BasicPlayer (object)
+
+Basic player statistic information object
+
+##Properties
++ name: `Jagernaut` (string, required) - the displayed username of the army member
++ fraction: `OPFOR` (string, required) - fraction of the player
++ kill: 5 (number, required) - sum of kills
++ friendlyFire: 0 (number, required) - sum of friendly fire kills
++ vehicle: 1 (number, required) - sum of vehicle kills
++ death: 3 (number, required) - sum of deaths
++ respawn: 2 (number, required) - sum of respawns
++ flagTouch: 1 (number, required) - sum of flag captures
++ revive: 0 (number, required) - sum of revives
+
+
+# CampaignPlayer (BasicPlayer)
+A player campaign statistics object
+
+## Properties
++ _id: `5ab68d42f547ed304064e5f7` (string, required) - unique id of the army member
++ warId: `5abf65ae3fc5fa349ffd5ca3` (string, required) - war in which this player took part
++ steamUUID: `76561192214911200` (string, required) - unique ID for STEAM platform account
++ sort: 1 (number, required) - sorting number calculated by (kill + revive + flagTouch - friendlyFire - death - respawn)
++ timestamp: `2018-02-24T01:01:25.825Z` - the entity creation timestamp
++ updatedAt: `2018-02-24T01:01:25.825Z` - the version timestamp
++ __v: 0 (number, required) - the version number of the object
+
+
+# HighscorePlayer (BasicPlayer)
+A player object as resturned for the highscore arrays
+
+## Properties
++ num: 1
diff --git a/api/apib/data_structures/_user.apib b/api/apib/data_structures/_user.apib
index 4473b24..b9d9d98 100644
--- a/api/apib/data_structures/_user.apib
+++ b/api/apib/data_structures/_user.apib
@@ -1,4 +1,4 @@
-# User
+# User (object)
 A participant managed in the system
 
 ## Properties
diff --git a/api/apib/data_structures/_war.apib b/api/apib/data_structures/_war.apib
index 848b22c..aac5b1f 100644
--- a/api/apib/data_structures/_war.apib
+++ b/api/apib/data_structures/_war.apib
@@ -1,4 +1,4 @@
-# War
+# War (object)
 A war as used in statistics
 
 ## Properties
diff --git a/api/apib/data_structures/index.apib b/api/apib/data_structures/index.apib
index bda83b5..e53caff 100644
--- a/api/apib/data_structures/index.apib
+++ b/api/apib/data_structures/index.apib
@@ -12,6 +12,8 @@
 
 :[Gists](_decoration.apib)
 
+:[Gists](_player.apib)
+
 :[Gists](_promotion.apib)
 
 :[Gists](_rank.apib)
diff --git a/api/apib/dev-doc.apib b/api/apib/dev-doc.apib
index a87ba42..571988c 100644
--- a/api/apib/dev-doc.apib
+++ b/api/apib/dev-doc.apib
@@ -42,6 +42,8 @@ FORMAT: 1A
 
 # Group Players
 
+:[Gists](statistics/players.apib)
+
 # Group Promotion
 
 :[Gists](army-management/promotions.apib)
diff --git a/api/apib/statistics/players.apib b/api/apib/statistics/players.apib
new file mode 100644
index 0000000..2042bb6
--- /dev/null
+++ b/api/apib/statistics/players.apib
@@ -0,0 +1,34 @@
+### Get Player Highscore [GET /ranking/{campaignId}]
+
+List highscores for player statistics over all wars of a certain campaign.
+Every highscore player object contains a field *sum*, representing its order number in the collection
+
++ Parameters
+    + campaignId: `5abd55ea9e30a76bfef747d6` (string, required) - unique id of the campaign
+
++ Response 200
+
+    + Attributes
+        + kill (array[HighscorePlayer],required) - player highscore for kill
+        + death (array[HighscorePlayer],required) - player highscore for death
+        + friendlyFire (array[HighscorePlayer],required) - player highscore for friendly fire
+        + vehicle (array[HighscorePlayer],required) - player highscore for vehicle
+        + revive (array[HighscorePlayer],required) - player highscore for revive
+        + respawn (array[HighscorePlayer],required) - player highscore for respawn
+        + flagTouch (array[HighscorePlayer],required) - player highscore for flag captures
+
+
+### Get Player Campaign Statistics [GET /single/{campaignId}/{playerId}]
+
+Get statistics for a single player for all wars of a campaign he took part at
+
++ Parameters
+    + campaignId: `5abd55ea9e30a76bfef747d6` (string, required) - unique id of the campaign
+    + playerId: `5abf65ae3fc5fa349ffd5ca4` (string, required) - unique id of the player
+
++ Response 200
+
+    + Attributes
+        + name: `Pumarang` (string, required) - latest used playername
+        + campaign (Campaign,required) - campaign reflected from request is
+        + players (array[CampaignPlayer],required) - collection of player instances in the campaign