Document API

.markdownlint.yaml

@@ -0,0 +1,7 @@
+---
+# Disable duplicate heading warning, used in API docs for requests and responses
+MD024: false
+
+# Disable check for duplicate title in front matter, used to customize sidebar
+MD025:
+  front_matter_title: ""

docs/docs/api/Services/airplane-service.md

@@ -0,0 +1,94 @@
+---
+title: Airplane
+---
+
+# `AirplaneService`
+
+The `AirplaneService` implements the API endpoints that interact with airplanes
+in the game. Most importantly, it can be used to update the flight plan of each
+airplane.
+
+## Get Airplane
+
+The state of each airplane can be queried with the `GetAirplane` request. It
+takes the `id` of the airplane as an argument, and returns an instance of the
+[`Airplane`](/docs/api/types#airplane) message type.
+
+```protobuf
+rpc GetAirplane(GetAirplaneRequest) returns (GetAirplaneResponse);
+```
+
+### Request
+
+```protobuf
+message GetAirplaneRequest {
+  string id = 1;
+}
+```
+
+### Response
+
+```protobuf
+message GetAirplaneResponse {
+  Airplane airplane = 1;
+}
+```
+
+- The [status code] `NOT_FOUND` will be returned when no airplane with the given
+  `id` can be found.
+
+## Update Flight Plan
+
+The flight plan of an airplane can be updated with the `UpdateFlightPlan`
+request. The request takes the airplane's `id` and the new flight plan as an
+argument, and returns either a success or error response.
+
+```protobuf
+rpc UpdateFlightPlan(UpdateFlightPlanRequest) returns (UpdateFlightPlanResponse);
+```
+
+### Request
+
+```protobuf
+message UpdateFlightPlanRequest {
+  string id = 1;
+  repeated Node flight_plan = 2;
+}
+```
+
+### Response
+
+```protobuf
+message UpdateFlightPlanResponse {
+  oneof payload {
+    UpdateFlightPlanSuccess success = 1;
+    UpdateFlightPlanError error = 2;
+  }
+}
+```
+
+When the flight plan is successfully updated, an empty response will be
+returned.
+
+```protobuf
+message UpdateFlightPlanSuccess {}
+```
+
+When the flight plan cannot be updated, e.g. because the provided plan is not
+valid, a list of validation errors is returned.
+
+```protobuf
+message UpdateFlightPlanError {
+  enum ValidationError {
+    UNSPECIFIED = 0;
+    NODE_OUTSIDE_MAP = 1;
+    INVALID_STEP = 2;
+    SHARP_TURN = 3;
+    INVALID_START = 4;
+    RESTRICTED_NODE = 5;
+  }
+  repeated ValidationError errors = 1;
+}
+```
+
+[status code]: https://grpc.github.io/grpc/core/md_doc_statuscodes.html

docs/docs/api/Services/atc-service.md

@@ -0,0 +1,30 @@
+---
+title: Auto Traffic Control
+---
+
+# `AtcService`
+
+The `AtcService` provides information about **Auto Traffic Control** itself.
+
+## Get Version
+
+The current version of the game can be queried with the `GetVersion` request,
+which returns the [`Version`](/docs/api/types#version) message type.
+
+```protobuf
+rpc GetVersion(GetVersionRequest) returns (GetVersionResponse);
+```
+
+### Request
+
+```protobuf
+message GetVersionRequest {}
+```
+
+### Response
+
+```protobuf
+message GetVersionResponse {
+  Version version = 1;
+}
+```

docs/docs/api/Services/event-service.md

@@ -0,0 +1,42 @@
+---
+title: Event
+---
+
+# `EventService`
+
+The `EventService` streams changes in the game as events to the player.
+
+## Stream
+
+Players can subscribe to the event stream by calling the `Stream` endpoint on
+the `EventService`.
+
+```protobuf
+rpc Stream(StreamRequest) returns (stream StreamResponse) {}
+```
+
+### Request
+
+```protobuf
+message StreamRequest {}
+```
+
+### Response
+
+The event service returns a stream of events. See [Events](/docs/api/events) for
+more information on the different event types.
+
+```protobuf
+message StreamResponse {
+  oneof event {
+    AirplaneCollided airplane_collided = 1;
+    AirplaneDetected airplane_detected = 2;
+    AirplaneLanded airplane_landed = 3;
+    AirplaneMoved airplane_moved = 4;
+    FlightPlanUpdated flight_plan_updated = 5;
+    LandingAborted landing_aborted = 6;
+    GameStarted game_started = 7;
+    GameStopped game_stopped = 8;
+  }
+}
+```

docs/docs/api/Services/game-service.md

@@ -0,0 +1,60 @@
+---
+title: Game
+---
+
+# `GameService`
+
+The `GameService` can be used to start a new game or to query the status of the
+current game session.
+
+## Get Game
+
+The state of the current game session can be queried with the `GetGame` request.
+
+```protobuf
+rpc GetGameState(GetGameStateRequest) returns (GetGameStateResponse);
+```
+
+### Request
+
+```protobuf
+message GetGameStateRequest {}
+```
+
+### Response
+
+The response contains the `game_state`, which can be either `ready` or
+`running`. When the game state is `ready`, no game session is currently running
+and the player is either in the _main menu_ or in the _game over_ screen.
+
+```protobuf
+message GetGameStateResponse {
+  enum GameState {
+    GAME_STATE_UNSPECIFIED = 0;
+    GAME_STATE_READY = 1;
+    GAME_STATE_RUNNING = 2;
+  }
+  GameState game_state = 1;
+}
+```
+
+## Start Game
+
+A new game session can be started by calling the `StartGame` endpoint of the
+`GameService`. If a game is already running, nothing will happen.
+
+```protobuf
+rpc StartGame(StartGameRequest) returns (StartGameResponse);
+```
+
+### Request
+
+```protobuf
+message StartGameRequest {}
+```
+
+### Response
+
+```protobuf
+message StartGameResponse {}
+```

docs/docs/api/Services/map-service.md

@@ -0,0 +1,58 @@
+---
+title: Map
+---
+
+# `MapService`
+
+The `MapService` can be queried to get the map of the current game session, or
+to convert between the different coordinate systems.
+
+## Get Map
+
+The map used in the current game session can be retrieved using the `GetMap`
+endpoint.
+
+```protobuf
+rpc GetMap(GetMapRequest) returns (GetMapResponse);
+```
+
+### Request
+
+```protobuf
+message GetMapRequest {}
+```
+
+### Response
+
+```protobuf
+message GetMapResponse {
+  Map map = 1;
+}
+```
+
+## Node to Point
+
+Nodes are a location on the routing grid, while points are a location on the
+map. A [`Node`](/docs/api/types#node) can be converted to a
+[`Point`](/docs/api/types#point) through the `NodeToPoint` endpoint, but points
+cannot be converted to nodes.
+
+```protobuf
+rpc NodeToPoint(NodeToPointRequest) returns (NodeToPointResponse);
+```
+
+### Request
+
+```protobuf
+message NodeToPointRequest {
+  Node node = 1;
+}
+```
+
+### Response
+
+```protobuf
+message NodeToPointResponse {
+  Point point = 1;
+}
+```