Rework frontend API spec (#33)

* Rework frontend API spec

* Fix typo

* Use second timestamps at points

We only need millisecond accuracy in location.

* Fix TS highlighting

* Update backend-schema-proposal.md

* Rework /routes into /dashboard

Allows us to avoid overfetching by dumping all relevant main screen info into a single response body.

* Indicate time drift alerts

Can happen, likely need to have it on the admin panel

* Fix outage naming

* Clarify outage location reporting

Co-authored-by: Grant Lemons <grant0lemons@gmail.com>

* Fix typescript block formatting

* Use millis for hardware -> backend

* Revamp van related routes

Cluster van status and ridership into a new set of routes that also allows van route relations and van status to be obtained and changed.

* autoformat ts snippets (comma to simicolon for interface)

* change to js Date for timestamps to frontend

* Indicate route IDs better

Also includes in stops

* Use correct typescript nullable notation

---------

Co-authored-by: Grant Lemons <grant0lemons@gmail.com>

backend/backend-schema-proposal.md

@@ -6,7 +6,7 @@ POST `/location/{van_id}`
 
 - `van_id` is an 8-bit integer
 - Message body is `(lat, lon, timestamp)`, where `lat` & `lon` are 64-bit doubles,
-  and `timestamp` is a UNIX timestamp
+  and `timestamp` is a UNIX timestamp in milliseconds
   - This minimizes network usage
 - The server should discard any timestamp earlier than the most recent
 - The server should discard any timestamp more than 1 min into the future
@@ -19,7 +19,7 @@ POST `/stats/ridership/{van_id}`
 
 - `van_id` is an 8-bit integer
 - Request body is `(ridership, timestamp)`, where `ridership` is an 8-bit int
-  and `timestamp` is a UNIX timestamp
+  and `timestamp` is a UNIX timestamp in milliseconds
 - The server should discard any timestamp earlier than the most recent
 - The server should discard any timestamp more than 1 min into the future
   (and add admin status message?)
@@ -30,7 +30,8 @@ GET `/request/{van_id}`
 
 - `van_id` is an 8-bit integer
 - Subscribes the hardware to SSE for ADA requests
-- Responses are in the format `(lat, lon)` where `lat` & `lon` are 64-bit doubles
+- Responses are in the format `(lat, lon, timestamp)` where `lat` & `lon` are
+  64-bit doubles and `timestamp` is a 64-bit UNIX timestamp in milliseconds
 - Message authentication header is a bearer token that is unique per van
 - Communication is HTTPS only
 
@@ -39,86 +40,191 @@ GET `/request/{van_id}`
 GET `/location`
 
 - Subscribes the client to SSE triggered by new coordinates to any van
-- Responses are in the format `(lat, lon, route_id, van_id, timestamp)` where
-  `van_id` & `route_id` are 8-bit ints, `lat` & `lon` are 64-bit doubles, and
-  `timestamp` is a UNIX timestamp
 - Any response with an earlier timestamp than the most recent should be discarded
+- Excessive time drifting will be detected on backend and reported in admin panel
 - Any timestamp more than 1 min in the future should be discarded
 - Communication can be HTTP or HTTPS, but HTTPS is already being used
+- Response body is defined in JSON as per the following typescript spec:
 
-GET `/routes`
+```typescript
+interface Location {
+  vanId: number;
+  routeId: number;
+  location: Coordinate;
+  timestamp: Date;
+}
+```
 
-- Retrieves a predefined list of routes and their waypoints
+GET `/dashboard`
+
+- Retrieves all data to show on the main screen of the frontend
 - Coordinates are defined in a config file
-- Responses are a JSON array of routes in the following format:
+- Alerts with start times in the future or end times in the past are discarded
+- Response body is defined in JSON as per the following typescript spec:
 
 ```typescript
-[{
-    name: string
-    waypoints: [{
-        index: int,
-        stop: bool,
-        name: string | undefined,
-        longitude: double,
-        latitude: double,
-    }]
-}]
+interface Dashboard {
+  routes: Route[];
+  stops: Stop[];
+  alert?: Alert;
+}
+
+interface Alert {
+  body: string;
+  startTimestamp: Date;
+  endTimestamp: Date;
+}
+
+interface Route {
+  id: number;
+  name: string;
+  active: boolean;
+  waypoints: Coordinate[]; // Already ordered by index in backend
+}
+
+interface Stop {
+  id: number;
+  name: string;
+  active: boolean;
+  location: Coordinate;
+  routeIds: number[]
+}
 ```
 
 POST `/request`
 
 - Makes ADA request for the driver
 - The handler for this will decide which van is most appropriate and send an SSE
-- Request body is in the format `(lat, lon, timestamp)` where `lat` & `lon` are
-  64-bit doubles describing the client's coordinates
 - Any request with a timestamp more than 10 min out-of-date (or in the future)
   should be discarded
 - Communication is HTTPS only
+- Request body is defined in JSON as per the following typescript spec:
+
+```typescript
+interface Request {
+  location: Coordinate;
+  timestamp: Date;
+}
+```
 
 ## Outages
 
-POST `/admin/outage/{route_id}/{end_datetime}`
+GET `/admin/outage`
 
-- `route_id` is an 8-bit integer
-- `end_datetime` is a UNIX timestamp
-  representing the end of the outage
+- Gets all scheduled route/stop outages to occur at some point in the future
 - Stops reporting the location of all vans registered to a route
 - Requests to a route will override any previous requests
 - Adds message to all status requests
+- Message authentication header is a bearer token with specific permissions
+  allowing admin actions
+- Can schedule an outage into the future, or schedule one now
+- Response body is defined in JSON as per the following typescript spec:
+
+```typescript
+type Outages = Outage[];
+
+interface Outage {
+  id: number;
+  body: string;
+  startTimestamp: Date;
+  endTimestamp: Date;
+  routeIdsDisabled: number[];
+  stopIdsDisabled: number[];
+}
+```
+
+POST `/admin/outages/`
+
+- Schedules a route/stop outage to occur at some point in the future
+- Stops reporting the location of all vans registered to a route or stop
+- Requests to a route will override any previous requests
+- Adds message to all status requests
 - Message authentication header is a bearer token with specific permissions
   allowing admin actions
 - Communication is HTTPS only
+- Can schedule an outage into the future, or schedule one now
+- Request body is defined in JSON as per the following typescript spec:
+
+```typescript
+interface Outage {
+  body: string;
+  startTimestamp: Date;
+  endTimestamp: Date;
+  routeIdsDisabled: number[];
+  stopIdsDisabled: number[];
+}
+```
 
-DELETE `/admin/outage/{route_id}`
+DELETE `/admin/outages/{outage_id}`
 
-- `route_id` is an 8-bit integer
+- `outage_id` is an 8-bit integer
 - Stops reporting the location of all vans registered to a route
 - Adds message to all status requests
 - Message authentication header is a bearer token with specific permissions
   allowing admin actions
 - Communication is HTTPS only
 
+## Vans
+
+GET `/admin/vans`
+
+- Reports current active vans (and assigned route IDs)
+- Message authentication header is a bearer token with specific permissions
+  allowing admin actions
+- Communication is HTTPS only
+- Response body is defined in JSON as per the following typescript spec:
+
+```typescript
+type Vans = Van[];
+
+interface Van {
+  id: number;
+  routes: number[]; // Route ID list, empty if not running
+}
+```
+
+POST `/admin/vans/{van_id}`
+
+- Change assigned routes of specified van
+- Message authentication header is a bearer token with specific permissions
+  allowing admin actions
+- Communication is HTTPS only
+- Request body is defined in JSON as per the following typescript spec:
+
+```typescript
+type Van = number[]; // Route ID list, empty if not running
+```
+
+GET `/stats/ridership/{van_id}`
+
+- Gets ridership information from the van with the specified ID
+- This is likely an expensive calculation, hence why it's in its own route
+- Message authentication header is a bearer token with specific permissions
+  allowing admin actions
+- Communication is HTTPS only
+- Response body is defined in JSON as per the following typescript spec:
+
+```typescript
+// NOTE: Not final format, unsure exactly what we should be calculating or
+whether we want to directly provide each datapoint to stakeholders
+type Ridership = RidershipLog[];
+
+interface RidershipEntry {
+  timestamp: Date;
+  location: Coordinate;
+  entered: number;
+  exited: number;
+}
+```
+
 ## Status
 
 GET `/admin/status`
 
 - Reports status + server health info
   - Uptime
-  - Current active vans (and IDs)
   - Current number of clients subscribed
-  - Current ridership figures from each van
 - Response body is serialized JSON w/ an array holding data per van
 - Message authentication header is a bearer token with specific permissions
   allowing admin actions
 - Communication is HTTPS only
-
-GET `/admin/status/{van_id}`
-
-- Reports detailed van status
-  (is the same as `/admin/status`, but only the specified van)
-  - Is van active?
-  - Current ridership figures from the van
-- Response body is serialized JSON
-- Message authentication header is a bearer token with specific permissions
-  allowing admin actions
-- Communication is HTTPS only