# LocationsApi document shapes

This service expects JSON request bodies for location creation and updates and
stores location documents in MongoDB.

Inbound JSON documents
- CreateLocationRequest (`POST /api/locations`)
  ```json
  {
    "name": "string",
    "coord": {
      "x": 0,
      "y": 0
    }
  }
  ```
- UpdateLocationRequest (`PUT /api/locations/{id}`)
  ```json
  {
    "name": "string"
  }
  ```
  `coord` cannot be updated.
- ResetWorldRequest (`POST /api/locations/reset-world`)
  ```json
  {
    "confirmDeleteAllNonOriginLocations": true,
    "confirmationPhrase": "RESET WORLD TO ORIGIN"
  }
  ```
  Both fields are required for the request to be accepted.
- GatherResourceRequest (`POST /api/locations/{id}/gather`)
  ```json
  {
    "characterId": "string (Character ObjectId)",
    "resourceKey": "wood"
  }
  ```

Stored documents (MongoDB)
- Location
  ```json
  {
    "id": "string (ObjectId)",
    "name": "string",
    "coord": {
      "x": 0,
      "y": 0
    },
    "biomeKey": "plains",
    "resources": [
      {
        "itemKey": "wood",
        "remainingQuantity": 100,
        "gatherQuantity": 3
      }
    ],
    "createdUtc": "string (ISO-8601 datetime)"
  }
  ```

Outbound JSON documents
- GatherResourceResponse (`POST /api/locations/{id}/gather`)
  ```json
  {
    "locationId": "string (ObjectId)",
    "characterId": "string (ObjectId)",
    "resourceKey": "wood",
    "quantityGranted": 3,
    "remainingQuantity": 97,
    "inventoryResponseJson": "string (raw InventoryApi response JSON)"
  }
  ```
- ResetWorldResponse (`POST /api/locations/reset-world`)
  ```json
  {
    "deletedLocationCount": 42,
    "remainingLocationCount": 2,
    "movedCharacterCount": 5,
    "reassignedInventoryItemCount": 19,
    "origin": {
      "id": "string (ObjectId)",
      "name": "Origin",
      "coord": {
        "x": 0,
        "y": 0
      },
      "biomeKey": "plains",
      "elevation": 0,
      "resources": [],
      "locationObject": null,
      "locationObjectResolved": true,
      "createdUtc": "string (ISO-8601 datetime)"
    },
    "limbo": {
      "id": "string (ObjectId)",
      "name": "World Limbo",
      "coord": {
        "x": -2000000000,
        "y": -2000000000
      },
      "biomeKey": "plains",
      "elevation": 0,
      "resources": [],
      "locationObject": null,
      "locationObjectResolved": true,
      "createdUtc": "string (ISO-8601 datetime)"
    }
  }
  ```