Plan/Plan/json-endpoints.md

# JSON endpoints

This document details what endpoints are available on a Plan webserver and what parameters they require.

What the endpoints return is not detailed to save time, as this document is written during implementation.

Parameters are given in the URL: `address/v1/<endpoint>?parameter=value&another=value`

If invalid parameters are given, the server will return 400 Bad Request.  
The body of the response is the error message

## Endpoints

### `GET /player/<playername>/raw` `GET /player/<player UUID>/raw`

Obtain all data in the database for a player. (Note that this is an exception to the /v1/ endpoints)

### Tab endpoints

Endpoints for tab specific number data, processed for display.

Required parameters: `server`

Parameter|Expected value|Description
--|--|--
`server` | Name or UUID of a Plan server | Used for identifying Plan server that the data should be about

#### `GET /v1/serverOverview` - Server Overview tab

#### `GET /v1/onlineOverview` - Online Activity Overview tab.

#### `GET /v1/sessionsOverview` - Sessions tab.

#### `GET /v1/playerVersus` - PvP & PvE tab.

#### `GET /v1/playerbaseOverview` - Playerbase Overview tab.

#### `GET /v1/performanceOverview`

### `GET /v1/players`

Obtain data for `/server` player list.

Required parameters: `server`

Parameter|Expected value|Description
--|--|--
`server` | Name or UUID of a Plan server | Used for identifying Plan server that the data should be about

### `GET /v1/sessions`

Obtain data for `/server` session accordion. Returns configurable amount of sessions.

Required parameters: `server`

Parameter|Expected value|Description
--|--|--
`server` | Name or UUID of a Plan server | Used for identifying Plan server that the data should be about

### `GET /v1/kills`

Obtain data for `/server` kills table. Returns 100 most recent kills.

Required parameters: `server`

Parameter|Expected value|Description
--|--|--
`server` | Name or UUID of a Plan server | Used for identifying Plan server that the data should be about

### `GET /v1/graph`

Obtain data for graphs.

Required parameters: `server` and `type`

Parameter|Expected value|Description
--|--|--
`server` | Name or UUID of a Plan server | Used for identifying Plan server that the data should be about
`type` | `performance`, `uniqueAndNew` | What kind of graph data should be given

Type | Description
-- | --
`performance` | TPS data points for last 6 months: Players Online, TPS, CPU, RAM, Chunks, Entities, Disk Space
`uniqueAndNew` | Player data points for each day, how many unique and how many new players were there each day. Last 180 days
`calendar` | Calendar data points for each day there is data for. Last 2 years.
`worldPie` | World Pie data of all sessions combined
`activity` | Activity stack graph and pie graph data
`geolocation` | World Map and bar graph data. World Map uses iso-a3 specification of Country codes and Bar graph uses country names.
`aggregatedPing` | Min, Avg, Max ping graph data.
`punchCard` | PunchCard graph data. (Scatter plot)

### `GET /v1/player`

Fetch all data for a player page

Required parameters: `player`

Parameter|Expected value|Description
--|--|--
`player` | Name or UUID of a player | Used for identifying player the data should be about