Added documentation in README.md.

2021-10-11 20:39:38 +02:00 · 2021-10-11 20:39:38 +02:00 · d1dff43bbd
parent aa9b7de1f4
commit d1dff43bbd
1 changed files with 126 additions and 1 deletions
--- a/README.md
+++ b/README.md
@ -1,3 +1,128 @@
 # ddstats-server

-This server will serve the API needed for DD Stats to work properly.
+This server will serve the API needed for DD Stats to work properly.
+
+# API Reference
+
+## Maps
+
+### Map count: `/api/maps/count`
+Returns the total amount of maps.
+
+Example output:
+```json
+{
+  "success": true,
+  "response": 2028
+}
+```
+
+### Get specific map: `/api/maps/get/:map`
+Returns the `map` (if found in the database). `map` has to be the full map name **and** URL encoded.
+
+Example output (`/api/maps/get/1Hook`):
+```json
+{
+  "success": true,
+  "response": {
+    "_id": "6154a3a3db94330b8f12682e",
+    "name": "1Hook",
+    "mapper": "Starkiller",
+    "release": "2020-11-15T14:00:00.000Z",
+    "category": "Race",
+    "rating": 5,
+    "awardPoints": 10,
+    "__v": 0,
+    "totalFinishes": 42
+  }
+}
+```
+
+Example output (`/api/maps/get/1ook`):
+```json
+{
+  "success": false,
+  "response": "No map found!"
+}
+```
+
+### Get all maps: `/api/maps/getAll`
+Returns all maps from the database.
+
+### Get a category: `/api/maps/category/:category`
+Returns all maps from `category` from the database.
+
+Valid categories:
+- Novice
+- Moderate
+- Brutal
+- Insane
+- Dummy
+- DDMaX
+- Oldschool
+- Solo
+- Race
+- Fun
+
+## Players
+
+### Player count: `/api/players/count`
+Returns the total amount of players.
+
+Example output:
+```json
+{
+  "success": true,
+  "response": 465362
+}
+```
+
+### Get specific player: `/api/players/get/:player`
+Returns the `player` (if found in the database). `player` has to be the full player name **and** URL encoded.
+
+Example output (`/api/players/get/Yumiko`):
+```json
+{
+  "success": true,
+  "response": {
+    "_id": "6158a7f96f251f358de0e78e",
+    "name": "Yumiko",
+    "firstFinish": "2015-07-14T22:52:24.000Z",
+    "__v": 0,
+    "points": 5944,
+    "rankPoints": 356,
+    "teamPoints": 171,
+    "pointsThisWeek": 257
+  }
+}
+```
+
+Example output (`/api/players/get/Yumi`):
+```json
+{
+  "success": false,
+  "response": "No player found!"
+}
+```
+
+## Searching
+You can search both for players and maps in a more *advanced* way. You can provide a case-insensitive regex or search term to get all matching entries. This is, however, paginated...
+
+- Search for player: `/api/players/search?q=name`
+- Search for map: `/api/maps/search?q=name`
+
+### Options (queries)
+These are queries you can use:
+- `q` : [String | RegExp] → This is the actual search term or regex.
+- `sort` : [String = field_name] → This chooses what field to sort by. Some example fields:
+    - `name` (player or map)
+    - `points` (player)
+    - `releaseDate` (map)
+- `order` : [String = asc | desc] → This chooses between ordering it by **asc**ending or **desc**ending order.
+- `page` : [Int = page_num] → This chooses what page to load in.
+- `byMapper` : [Boolean] (only for maps) → Searches by the mapper's name instead of by the map's name.
+
+### Examples
+- `/api/players/search?q=Yumiko&sort=points&order=desc` would search for players with `Yumiko` in their names, sort by their points in descending order (the one wiht the most points first).
+- `/api/players/search?q=burnyllama` would search for players with `burnyllama` in their names.
+- `/api/players/search?q=^[0-9]` would search for players with a name begining with a number.