Update API Reference to match new sidebar.

docs/api/01-introduction.md

@@ -0,0 +1,48 @@
+---
+title: Introduction
+---
+
+# Introduction
+
+Battlesnake is played by responding to simple webhooks sent to your server by the game engine. Developers build a web server that receives and responds to HTTP requests, and how your server responds to these requests controls how your Battlesnake behaves.
+
+
+## Requests
+
+All requests made from the game engine to your Battlesnake server will have the following properties.
+
+### Content-Type
+
+Requests will contain [JSON-encoded](https://www.json.org/) request bodies. Your server is responsible for receiving and parsing this data correctly (although most modern web frameworks come with easy ways to handle this type of request).
+
+
+## Responses
+
+All responses from your Battlesnake server must abide by these rules when responding to game engine requests. If your server fails to send a valid response in any way, the game engine will consider it an error and act accordingly.
+
+### Content-Type
+
+Valid responses must be JSON-encoded strings with the Content-Type header set to \`_application/json\`_.
+
+### Status Codes
+
+Valid responses must return an _HTTP 200 OK_ status code. If any other status code is returned, the game engine will consider it an invalid response.
+
+### Latency & Timeouts
+
+Your Battlesnake server must respond to requests made by the game engine within the given timeout value. This value is provided in the request body as a [property on the game object](api/objects/game).
+
+In most games this will be 500ms, however, this value can technically vary from game to game. If your response does not reach the game engine within the specified timeout, the game engine will consider it an invalid response.
+
+:::tip
+Note that these time limits must include round-trip latency between the game engine and your server - be sure to take that into consideration when deciding how long to spend computing your response.
+:::
+
+
+## Response Error Handling
+
+Any invalid responses will be treated as errors by the game engine, and your Battlesnake's next move will be chosen for you - even if that means certain elimination.
+
+**An error on the first move of a game** will move your Battlesnake `up` by default. This value is hardcoded into the game engine with no particular meaning behind it.
+
+**Errors on subsequent turns** will repeat your previous move. For example, if your Battlesnake successfully moves `right` on turn N, a timeout on turn N+1 will result in your Battlesnake moving `right` again. This applies even if the game engine chose your move for you on the previous turn due to an error.

docs/api/02-webhooks.md

@@ -0,0 +1,116 @@
+---
+title: Webhooks
+---
+
+# Webhooks
+
+This page documents the technical details of the webhooks sent from the game engine to your Battlesnake server. They all originate from the Battlesnake Server URL that you provide when creating your Battlesnake in the dashboard.
+
+
+## Battlesnake Details
+
+HTTP Request: `GET /`
+
+An empty GET request made to the root URL of your Battlesnake, used to load customization, check latency, and verifying successful communications between the game engine and your Battlesnake.
+
+#### Request Data
+
+None, the game engine will send an empty request body.
+
+#### Response Properties
+
+| **Property**  | **Type**            | **Description**                                                                                                                                           |
+| -------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **apiversion** | string _(required)_ | Version of the Battlesnake API implemented by this Battlesnake. Currently only API version 1 is valid. <em>Example: "1"</em>                              |
+| **author**     | string _(optional)_ | Username of the author of this Battlesnake. If provided, this will be used to verify ownership. <em>Example: "BattlesnakeOfficial"</em>                   |
+| **color**      | string _(optional)_ | Hex color code used to display this Battlesnake. Must start with "#", followed by 6 hexadecimal characters. <em>Example: "#888888"</em>                                |
+| **head**       | string _(optional)_ | Head customization. <em>Example: "default"</em>                |
+| **tail**       | string _(optional)_ | Tail customization. <em>Example: "default"</em>                |
+| **version**    | string _(optional)_ | An optional version string for your Battlesnake. This value is not used in gameplay, but can be useful for tracking deployments on your end.                                                                                                               |
+
+See [Customization Guide](/guides/customizations) for more info about changing your Battlesnake's color, head, and tail.
+
+#### Example Response
+
+```json title="200 OK"
+{
+  "apiversion": "1",
+  "author": "MyUsername",
+  "color": "#888888",
+  "head": "default",
+  "tail": "default",
+  "version": "0.0.1-beta"
+}
+```
+
+## Game Started
+
+HTTP Request: `POST /start`
+
+Your Battlesnake will receive this request when it has been entered into a new game that is about to begin. Every game has a unique ID that can be used to allocated resources or data you may need. Your response to this request will be ignored.
+
+#### Request Data
+
+| **Parameter**                      | **Type** | **Description**                                                               |
+| ---------------------------------- | -------- | ----------------------------------------------------------------------------- |
+| **game**                           | object   | [Game Object](objects/game) describing the game being played.                 |
+| **turn**                           | integer  | Turn number (always 0 for new games).                                         |
+| **board**                          | object   | [Board Object](objects/board) describing the initial state of the game board. |
+| **you**                            | object   | [Battlesnake Object](objects/battlesnake) describing your Battlesnake.        |
+
+#### Response Properties
+
+Responses to this request are ignored by the game engine.
+
+
+## Move
+
+HTP Request: `POST /move`
+
+This request will be sent for every turn of every game that your Battlesnake plays. Use the information provided to determine how your Battlesnake will move on that turn, either up, down, left, or right.
+
+#### Request Parameters
+
+| **Parameter**                      | **Type** | **Description**                                                               |
+| ---------------------------------- | -------- | ----------------------------------------------------------------------------- |
+| **game**                           | object   | [Game Object](objects/game) describing the game being played.                 |
+| **turn**                           | integer  | Turn number for this move.                                                    |
+| **board**                          | object   | [Board Object](objects/board) describing the initial state of the game board. |
+| **you**                            | object   | [Battlesnake Object](objects/battlesnake) describing your Battlesnake.        |
+
+
+#### Response Properties
+
+| **Property**  | **Type**            | **Description**                                                                                      |
+| ------------- | ------------------- | ---------------------------------------------------------------------------------------------------- |
+| **move**      | string              | Your Battlesnake's move for this turn. Valid moves are "up", "down", "left", or "right".             |
+| **shout**     | string _(optional)_ | An optional message sent to all other Battlesnakes on the next turn. Must be 256 characters or less. |
+
+
+#### Example Response
+
+```json title="200 OK"
+{
+  "move": "up",
+  "shout": "Moving up!"
+}
+```
+
+## Game Over
+
+HTTP Request: `POST /end``
+
+Your Battlesnake will receive this request whenever a game it was playing has ended. Use it to learn how your Battlesnake won or lost and deallocate any server-side resources. Your response to this request will be ignored.
+
+#### Request Data
+
+| **Parameter**                      | **Type** | **Description**                                                               |
+| ---------------------------------- | -------- | ----------------------------------------------------------------------------- |
+| **game**                           | object   | [Game Object](objects/game) describing the game being played.                 |
+| **turn**                           | integer  | Final turn number.                                                            |
+| **board**                          | object   | [Board Object](objects/board) describing the initial state of the game board. |
+| **you**                            | object   | [Battlesnake Object](objects/battlesnake) describing your Battlesnake.        |
+
+#### Response Properties
+
+Responses to this request are ignored by the game engine.

docs/api/03-objects/_category_.json

@@ -0,0 +1,3 @@
+{
+    "label": "Objects"
+}

docs/api/objects/battlesnake.md → docs/api/03-objects/battlesnake.md

@@ -10,8 +10,8 @@ sidebar_position: 4
   "name": "Sneky McSnek Face",
   "health": 54,
   "body": [
-    {"x": 0, "y": 0}, 
-    {"x": 1, "y": 0}, 
+    {"x": 0, "y": 0},
+    {"x": 1, "y": 0},
     {"x": 2, "y": 0}
   ],
   "latency": "123",
@@ -38,4 +38,4 @@ sidebar_position: 4
 | **length**         | integer  | Length of this Battlesnake from head to tail. Equivalent to the length of the body array.<em>Example: 3</em>                                                                                                                            |
 | **shout**          | string   | Message shouted by this Battlesnake on the previous turn.<em>Example: "why are we shouting??"</em>                                                                                                                                      |
 | **squad**          | string   | The squad that the Battlesnake belongs to. Used to identify squad members in Squad Mode games.<em>Example: "1"</em>                                                                                                                     |
-| **customizations** | object   | The collection of customizations that control how this Battlesnake is displayed. Properties have the same restrictions and limitations as described in the [GET / API Request](../requests/info.md). _Example: {"color":"#888888", "head":"default", "tail":"default" }_ |
+| **customizations** | object   | The collection of customizations that control how this Battlesnake is displayed. _Example: {"color":"#888888", "head":"default", "tail":"default" }_ |

docs/api/objects/board.md → docs/api/03-objects/board.md

@@ -13,13 +13,13 @@ The game board is represented by a standard 2D grid, oriented with (0,0) in the
   "height": 11,
   "width": 11,
   "food": [
-    {"x": 5, "y": 5}, 
-    {"x": 9, "y": 0}, 
+    {"x": 5, "y": 5},
+    {"x": 9, "y": 0},
     {"x": 2, "y": 6}
   ],
   "hazards": [
-    {"x": 0, "y": 0}, 
-    {"x": 0, "y": 1}, 
+    {"x": 0, "y": 0},
+    {"x": 0, "y": 1},
     {"x": 0, "y": 2}
   ],
   "snakes": [
@@ -35,5 +35,5 @@ The game board is represented by a standard 2D grid, oriented with (0,0) in the
 | **height**   | integer  | The number of rows in the y-axis of the game board. <em>Example: 11</em>                                                                                                                                              |
 | **width**    | integer  | The number of columns in the x-axis of the game board. <em>Example: 11</em>                                                                                                                                           |
 | **food**     | array    | Array of coordinates representing food locations on the game board. <em>Example: [{"x": 5, "y": 5}, ..., {"x": 2, "y": 6}]</em>                                                                                       |
-| **hazards**  | array    | Array of coordinates representing hazardous locations on the game board. These will only appear in some [game modes](guides/playing/modes.md). <em>Example: [{"x": 0, "y": 0}, ..., {"x": 0, "y": 1}]</em>            |
-| **snakes**   | array    | Array of [Battlesnake Objects](battlesnake.md) representing all Battlesnakes remaining on the game board (including yourself if you haven't been eliminated). <em>Example: [{"id": "snake-one", ...}, ...]</em>       |
+| **hazards**  | array    | Array of coordinates representing hazardous locations on the game board. <em>Example: [{"x": 0, "y": 0}, ..., {"x": 0, "y": 1}]</em>            |
+| **snakes**   | array    | Array of [Battlesnake Objects](./battlesnake) representing all Battlesnakes remaining on the game board (including yourself if you haven't been eliminated). <em>Example: [{"id": "snake-one", ...}, ...]</em>       |

docs/api/objects/game.md → docs/api/03-objects/game.md

@@ -22,6 +22,6 @@ sidebar_position: 1
 | ------------ | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | **id**       | string                   | A unique identifier for this Game. <em>Example: "totally-unique-game-id"</em>                                                                                                                                                                                                          |
 | **ruleset**  | object                   | Information about the ruleset being used to run this game. <em>Example: {"name": "standard", "version": "v1.2.3"}</em>                                                                                                                                                                 |
-| **map**      | string                   | The name of the map used to populate the game board with snakes, food, and hazards. <em>Example: "standard"</em> See [Game Maps](game-maps.md)                                                                                                                                         |
+| **map**      | string                   | The name of the map being played on. <em>Example: "standard"</em>     |
 | **timeout**  | integer _(milliseconds)_ | How much time your snake has to respond to requests for this Game. <em>Example: 500</em>                                                                                                                                                                                               |
 | **source**   | string                   | The source of this game. One of:<ul><li>tournament</li><li>league <em>(for League Arenas)</em></li><li>arena <em>(for all other Arenas)</em></li><li>challenge</li><li>custom <em>(for all other games sources)</em></li></ul>The values for this field may change in the near future. |

docs/api/objects/ruleset-settings.md → docs/api/03-objects/ruleset-settings.md

@@ -5,7 +5,7 @@ sidebar_position: 3
 # RulesetSettings
 
 ```json
-"settings": {
+{
   "foodSpawnChance": 25,
   "minimumFood": 1,
   "hazardDamagePerTurn": 14,

docs/api/objects/ruleset.md → docs/api/03-objects/ruleset.md

@@ -14,6 +14,6 @@ sidebar_position: 2
 
 | **Property** | **Type** | **Description**                                                                                                                                                                                                                                       |
 | ------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **name**     | string   | Name of the ruleset being used to run this game. Possible values include: standard, solo, royale, squad, constrictor, wrapped. See [Game Modes](../../guides/playing/modes.md) for more information on each ruleset. <em>Example: "standard"</em>     |
+| **name**     | string   | Name of the ruleset being used to run this game. <em>Example: "standard"</em>     |
 | **version**  | string   | The release version of the [Rules](https://github.com/BattlesnakeOfficial/rules) module used in this game. <em>Example: "version": "v1.2.3"</em>                                                                                                      |
-| **settings** | object   | A collection of [specific settings](ruleset-settings.md) being used by the current game that control how the rules are applied.                                                                                                                       |
+| **settings** | object   | A collection of [specific settings](ruleset-settings) being used by the current game that control how the rules are applied.                                                                                                                       |

docs/api/example-move.md → docs/api/04-example-move.md

@@ -4,7 +4,7 @@ sidebar_position: 4
 
 # Example Move Request
 
-### Move API Request
+### Move Request
 
 ```json title="POST /move"
 {
@@ -28,8 +28,8 @@ sidebar_position: 4
     "height": 11,
     "width": 11,
     "food": [
-      {"x": 5, "y": 5}, 
-      {"x": 9, "y": 0}, 
+      {"x": 5, "y": 5},
+      {"x": 9, "y": 0},
       {"x": 2, "y": 6}
     ],
     "hazards": [
@@ -41,8 +41,8 @@ sidebar_position: 4
         "name": "My Snake",
         "health": 54,
         "body": [
-          {"x": 0, "y": 0}, 
-          {"x": 1, "y": 0}, 
+          {"x": 0, "y": 0},
+          {"x": 1, "y": 0},
           {"x": 2, "y": 0}
         ],
         "latency": "111",
@@ -54,14 +54,14 @@ sidebar_position: 4
           "head":"pixel",
           "tail":"pixel"
         }
-      }, 
+      },
       {
         "id": "snake-b67f4906-94ae-11ea-bb37",
         "name": "Another Snake",
         "health": 16,
         "body": [
-          {"x": 5, "y": 4}, 
-          {"x": 5, "y": 3}, 
+          {"x": 5, "y": 4},
+          {"x": 5, "y": 3},
           {"x": 6, "y": 3},
           {"x": 6, "y": 2}
         ],
@@ -82,8 +82,8 @@ sidebar_position: 4
     "name": "My Snake",
     "health": 54,
     "body": [
-      {"x": 0, "y": 0}, 
-      {"x": 1, "y": 0}, 
+      {"x": 0, "y": 0},
+      {"x": 1, "y": 0},
       {"x": 2, "y": 0}
     ],
     "latency": "111",
@@ -99,7 +99,7 @@ sidebar_position: 4
 }
 ```
 
-### Move API Response
+### Move Response
 
 ```json title="200 OK"
 {