API Reference - TheAbysmalKraken/NatakAPI GitHub Wiki

The Natak API is based on HTTP REST conventions, accepts JSON request bodies and returns JSON response bodies.

Base URL

https://api.natak.dev/api/v1/natak/

Authentication

Currently none.

Rate Limiting

All rate limits are per-client.

  • Default - 20 requests per 5 seconds
    • Sliding window policy
  • Create Game - 10 requests per hour
    • Token bucket policy
    • Regenerates 1 token per hour

Errors

{
  "statusCode": 404
  "message": "Game not found by specified identifier.",
  "type": "Game.NotFound"
}
  • statusCode - integer
  • message - string
  • type - string

Enums

PlayerColour

  • 0 (no colour/unowned)
  • 1
  • 2
  • 3
  • 4

ResourceType

  • 0 - None
  • 1 - Wood
  • 2 - Clay
  • 3 - Animal
  • 4 - Food
  • 5 - Metal

HexType

  • 0 - None
  • 1 - Wood
  • 2 - Clay
  • 3 - Animal
  • 4 - Food
  • 5 - Metal

GrowthCardType

  • 0 - Soldier
  • 1 - Roaming
  • 2 - Wealth
  • 3 - Gatherer
  • 4 - Victory Point

PortType

  • 0 - Three-to-one
  • 1 - Wood
  • 2 - Clay
  • 3 - Animal
  • 4 - Food
  • 5 - Metal

GameState

  • 0 - A player is placing a setup village
  • 1 - A player is placing a setup road
  • 2 - A player has finished a setup turn
  • 3 - Before the current player has rolled
  • 4 - After the current player has rolled
  • 5 - Building roaming roads
  • 6 - At least one player must finish discarding resources
  • 7 - The thief must be moved
  • 8 - A resource must be stolen
  • 9 - The game is finished

ActionType

  • 0 - Build a village
  • 1 - Build a road
  • 2 - Build a town
  • 3 - Roll the dice
  • 4 - End turn
  • 5 - Make a trade offer or trade with bank
  • 6 - Play a growth card
  • 7 - Discard resources
  • 8 - Move the thief
  • 9 - Steal a resource

Objects

Board

{
  "hexes": [
    {
      "point": {
        "x": 0,
        "y": 2
      },
      "resource": 4,
      "rollNumber": 12
    }
  ],
  "roads": [
    {
      "playerColour": -1,
      "firstPoint": {
        "x": 0,
        "y": 3
      },
      "secondPoint": {
        "x": 0,
        "y": 2
      }
    }
  ],
  "villages": [
    {
      "playerColour": 1,
      "point": {
        "x": 2,
        "y": 3
      }
    }
  ],
  "towns": [
    {
      "playerColour": 1,
      "point": {
        "x": 2,
        "y": 3
      }
    }
  ],
  "ports": [
    {
      "point": {
        "x": 2,
        "y": 0
      },
      "type": 1
    }
  ]
}
  • hexes - array of Hex
  • roads - array of Road
  • villages - array of Building
  • towns - array of Building
  • ports - array of Port

Building

{
  "playerColour": 2,
  "point": {
    "x": 4,
    "y": 2
  }
}
  • playerColour - PlayerColour
    • Colour of player who owns the building
  • point - Point
    • Coordinates of the building

Player

{
  "colour": 2,
  "soldiersPlayed": 0,
  "visibleVictoryPoints": 2,
  "totalResourceCards": 3,
  "totalGrowthCards": 0,
  "hasLargestArmy": false,
  "hasLongestRoad": false,
  "cardsToDiscard": 0,
  "remainingVillages": 3,
  "remainingTowns": 4,
  "remainingRoads": 13,
  "embargoedPlayerColours": [
    1,
    3
  ]
}
  • colour - PlayerColour
  • soldiersPlayed - integer
  • visibleVictoryPoints - integer
    • How many victory points the player has excluding victory point growth cards
  • totalResourceCards - integer
    • How many resource cards the player has
  • totalGrowthCards - integer
    • How many growth cards the player has
  • hasLargestArmy - bool
  • hasLongestRoad - bool
  • cardsToDiscard - integer
    • How many resource cards the player is required to discard
  • remainingVillages - integer
    • Number of villages the player has left to use
  • remainingTowns - integer
    • Number of towns the player has left to use
  • remainingRoads - integer
    • Number of roads the player has left to use
  • embargoedPlayerColours - array of PlayerColour
    • Colours of other players that this player has embargoed

DetailedPlayer

{
  "victoryPoints": 3,
  "resourceCards": {
    "1": 2,
    "2": 1,
    "3": 0,
    "4": 1,
    "5": 0
  },
  "playableGrowthCards": {
    "1": 0,
    "2": 0,
    "3": 0,
    "4": 0,
    "5": 1
  },
  "onHoldGrowthCards": {
    "1": 1,
    "2": 0,
    "3": 0,
    "4": 0,
    "5": 0
  },
  "colour": 1,
  "soldiersPlayed": 0,
  "visibleVictoryPoints": 2,
  "totalResourceCards": 4,
  "totalGrowthCards": 2,
  "hasLargestArmy": false,
  "hasLongestRoad": false,
  "cardsToDiscard": 0,
  "remainingVillages": 3,
  "remainingTowns": 4,
  "remainingRoads": 13,
  "embargoedPlayerColours": [
    2,
    3
  ]
}
  • colour - PlayerColour
  • soldiersPlayed - integer
  • visibleVictoryPoints - integer
    • How many victory points the player has excluding victory point growth cards
  • totalResourceCards - integer
    • How many resource cards the player has
  • totalGrowthCards - integer
    • How many growth cards the player has
  • hasLargestArmy - bool
  • hasLongestRoad - bool
  • cardsToDiscard - integer
    • How many resource cards the player is required to discard
  • remainingVillages - integer
    • Number of villages the player has left to use
  • remainingTowns - integer
    • Number of towns the player has left to use
  • remainingRoads - integer
    • Number of roads the player has left to use
  • embargoedPlayerColours - array of PlayerColour
    • Colours of other players that this player has embargoed
  • victoryPoints - integer
    • How many victory points the player has including victory point growth cards
  • resourceCards - dictionary<ResourceType, integer>
    • The number of each type of resource card the player has
  • playableGrowthCards - dictionary<GrowthCardType, integer>
    • The number of each type of growth card the player has that can be played this turn
  • onHoldDevelopmentCards - dictionary<GrowthCardType, integer>
    • The number of each type of growth card the player has that cannot be played this turn

Game

{
  "id": "a87a4fac-c0f9-49c3-81bf-f2cce49c9c82",
  "playerCount": 4,
  "currentPlayerColour": 2,
  "gameState": 0,
  "actions": [
    0
  ],
  "player": {
    "victoryPoints": 0,
    "resourceCards": {
      "1": 0,
      "2": 0,
      "3": 0,
      "4": 0,
      "5": 0
    },
    "playableGrowthCards": {
      "1": 0,
      "2": 0,
      "3": 0,
      "4": 0,
      "5": 0
    },
    "onHoldGrowthCards": {
      "1": 0,
      "2": 0,
      "3": 0,
      "4": 0,
      "5": 0
    },
    "colour": 2,
    "soldiersPlayed": 0,
    "visibleVictoryPoints": 0,
    "totalResourceCards": 0,
    "totalGrowthCards": 0,
    "hasLargestArmy": false,
    "hasLongestRoad": false,
    "remainingVillages": 5,
    "remainingTowns": 4,
    "remainingRoads": 15,
    "embargoedPlayerColours": []
  },
  "players": [
    {
      "colour": 2,
      "soldiersPlayed": 0,
      "visibleVictoryPoints": 0,
      "totalResourceCards": 0,
      "totalGrowthCards": 0,
      "hasLargestArmy": false,
      "hasLongestRoad": false,
      "remainingVillages": 5,
      "remainingTowns": 4,
      "remainingRoads": 15,
      "embargoedPlayerColours": []
    },
    {
      "colour": 1,
      "soldiersPlayed": 0,
      "visibleVictoryPoints": 0,
      "totalResourceCards": 0,
      "totalGrowthCards": 0,
      "hasLargestArmy": false,
      "hasLongestRoad": false,
      "remainingVillages": 5,
      "remainingTowns": 4,
      "remainingRoads": 15,
      "embargoedPlayerColours": []
    },
    ...
  ],
  "board": {
    "hexes": [
      {
        "point": {
          "x": 0,
          "y": 2
        },
        "resource": 5,
        "rollNumber": 9
      },
      {
        "point": {
          "x": 0,
          "y": 3
        },
        "resource": 6,
        "rollNumber": 0
      },
      ...
    ],
    "roads": [
      {
        "playerColour": -1,
        "firstPoint": {
          "x": 0,
          "y": 3
        },
        "secondPoint": {
          "x": 0,
          "y": 2
        }
      },
      {
        "playerColour": -1,
        "firstPoint": {
          "x": 1,
          "y": 2
        },
        "secondPoint": {
          "x": 1,
          "y": 1
        }
      },
      ...
    ],
    "villages": [],
    "towns": [],
    "ports": [
      {
        "point": {
          "x": 2,
          "y": 0
        },
        "type": 1
      },
      {
        "point": {
          "x": 3,
          "y": 0
        },
        "type": 1
      },
      ...
    ]
  },
  "winner": null,
  "lastRoll": [
    5,
    1
  ],
  "largestArmyPlayer": null,
  "longestRoadPlayer": null,
  "remainingResourceCards": {
    "1": 19,
    "2": 19,
    "3": 19,
    "4": 19,
    "5": 19
  },
  "remainingGrowthCards": 25,
  "tradeOffer": {
    "isActive": false,
    "offer": {},
    "request": {},
    "rejectedBy": []
  }
}
  • id - string
  • playerCount - integer
  • currentPlayerColour - PlayerColour
    • Colour of the player who's turn it is
  • gameState - GameState
    • Used to give an indication of what actions can be performed
  • actions - array of ActionType
    • An array of the actions the current player is allowed to perform
    • Only based on the current GameState. Does not check, for example, that the player has a growth card to play even if they are allowed to play one
  • player - DetailedPlayer
    • Detailed information for the player the request was sent by
  • players - array of Player
    • Contains all players, including the player the request was sent by
  • board - Board
    • Current state of the board
  • winner - nullable PlayerColour
    • If someone has won the game, this will be not-null and the colour of the winning player
  • lastRoll - array of integer
    • The two integers most recently rolled by the dice
  • largestArmyPlayer - nullable PlayerColour
    • Colour of the player with the largest army
  • longestRoadPlayer - nullable PlayerColour
    • Colour of the player with the longest road
  • remainingResourceCards - Dictionary<ResourceType, integer>
    • Number of remaining resource cards for players to draw from
  • remainingGrowthCards - integer
    • Total number of remaining growth cards
  • tradeOffer - TradeOffer
    • The trade offer, either active or inactive

Hex

{
  "point": {
    "x": 0,
    "y": 2
  },
  "resource": 4,
  "rollNumber": 12
}
  • point - Point
    • Location of this hex on the board
  • resource - ResourceType
    • The resource this hex produces when rolled
  • rollNumber - integer
    • The roll number required for this hex to produce a resource

Point

{
  "x": 4,
  "y": 2
}
  • x - integer
  • y - integer

Port

{
  "point": {
    "x": 2,
    "y": 0
  },
  "type": 1
}
  • point - Point
    • The building location that allows access to this port
  • type - PortType
    • The type of trade this port allows when a player settles on it

Road

{
  "playerColour": -1,
  "firstPoint": {
    "x": 0,
    "y": 3
  },
  "secondPoint": {
    "x": 0,
    "y": 2
  }
}
  • playerColour - PlayerColour
    • The colour of the player this road belongs to
  • firstPoint - Point
    • One of the two building locations this road goes between
  • secondPoint - Point
    • The other of the two building locations this road goes between

NOTE: The two points of the road are not in a particular order

TradeOffer

{
  "isActive": true,
  "offer": {
    "1": 0,
    "2": 0,
    "3": 2,
    "4": 0,
    "5": 0
  },
  "request": {
    "1": 0,
    "2": 0,
    "3": 0,
    "4": 0,
    "5": 1
  },
  "rejectedBy": [
    1,
    3
  ]
}
  • isActive - boolean
    • True if the trade offer is open to be accepted/rejected
  • offer - Dictionary<ResourceType, integer>
    • The number of each type of resource the current player is offering to give
  • request - Dictionary<ResourceType, integer>
    • The number of each type of resource the current player wants to receive
  • rejectedBy - array of PlayerColour
    • Player colours who have rejected the offer, either manually or automatically via embargo

NOTE: Trade offers are automatically set to inactive if rejected by every player.

Endpoints

Create Game

Route

POST

Request Body

{
  "playerCount": 3,
  "seed": 0
}
  • playerCount - integer
    • Sets the number of players in the game
    • Must be either 3 or 4
  • seed (optional) - nullable integer
    • Sets the board layout seed

Success Response

200

{
  "gameId": "1bb8991d-a358-4d9d-b806-a2a8b8301287"
}
  • gameId - string

Get Game

Route

GET {gameId}/{playerColour}

Success Response

200

Returns a Game object.

Get Available Village Locations

Route

GET {gameId}/available-village-locations

Success Response

200

Returns an array of Point objects.

[
  {
    "x": 0,
    "y": 2
  },
  {
    "x": 0,
    "y": 3
  }
]

Get Available Road Locations

Route

GET {gameId}/available-road-locations

Success Response

200

Returns an array of Road objects.

[
  {
    "playerColour": -1,
    "firstPoint": {
      "x": 0,
      "y": 3
    },
    "secondPoint": {
      "x": 0,
      "y": 2
    }
  },
  {
    "playerColour": -1,
    "firstPoint": {
      "x": 1,
      "y": 2
    },
    "secondPoint": {
      "x": 0,
      "y": 2
    }
  }
]

Get Available Town Locations

Route

GET {gameId}/available-town-locations

Success Response

200

Returns an array of Point objects.

[
  {
    "x": 0,
    "y": 2
  },
  {
    "x": 0,
    "y": 3
  }
]

Build Village

Route

POST {gameId}/build/village

Request Body

{
  "point": {
    "x": 2,
    "y": 3
  }
}
  • point - Point

Success Response

204

Build Road

Route

POST {gameId}/build/road

Request Body

{
  "firstPoint": {
    "x": 2,
    "y": 3
  },
  "secondPoint": {
    "x": 3,
    "y": 3
  }
}
  • firstPoint - Point
  • secondPoint - Point

Success Response

204

Build Town

Route

POST {gameId}/build/town

Request Body

{
  "point": {
    "x": 2,
    "y": 3
  }
}
  • point - Point

Success Response

204

Roll Dice

Route

POST {gameId}/roll

Success Response

204

End Turn

Route

POST {gameId}/end-turn

Success Response

204

Buy Growth Card

Route

POST {gameId}/buy/growth-card

Success Response

204

Discard Resources

Route

POST {gameId}/{playerColour}/discard-resources

Request Body

{
  "resources": {
    "0": 1,
    "1": 2,
    "2": 0,
    "3": 0,
    "4": 0
  }
}
  • resources - Dictionary<ResourceType, integer>
    • A dictionary representing how many of each resource type the player wants to discard

Success Response

204

Move Thief

Route

POST {gameId}/move-thief

Request Body

{
  "moveThiefTo": {
    "x": 2,
    "y": 3
  }
}
  • moveThiefTo - Point

Success Response

204

Steal Resource

Route

POST {gameId}/steal-resource

Request Body

{
  "victimColour": 2
}
  • victimColour - PlayerColour
    • Colour of the player to steal from

Success Response

204

Make Trade Offer

Route

POST {gameId}/trade/player

Request Body

{
  "offer": {
    "0": 1,
    "1": 2,
    "2": 0,
    "3": 0,
    "4": 0
  },
  "request": {
    "0": 0,
    "1": 0,
    "2": 1,
    "3": 1,
    "4": 1
  }
}
  • offer - Dictionary<ResourceType, integer>
    • A dictionary representing how many of each resource type the player wants to give away in the trade
  • request - Dictionary<ResourceType, integer>
    • A dictionary representing how many of each resource type the player wants to receive from the trade

Success Response

204

Trade With Bank

Route

POST {gameId}/trade/bank

Request Body

{
  "resourceToGive": 3,
  "resourceToGet": 4
}
  • resourceToGive - ResourceType
    • The type of resource the player is giving to the bank
    • Will trade at the best rate the player has available
  • resourceToGet - ResourceType
    • The type of resource the player wants to receive

Success Response

204

Embargo Player

Route

POST {gameId}/{playerColour}/embargo-player

Request Body

{
  "playerColourToEmbargo": 2
}
  • playerColourToEmbargo - PlayerColour

Success Response

204

Remove Embargo

Route

POST {gameId}/{playerColour}/remove-embargo

Request Body

{
  "playerColourToEmbargo": 2
}
  • playerColourToRemoveEmbargoOn - PlayerColour

Success Response

204

Respond to Trade Offer

Route

POST {gameId}/trade/player/{accept}

Success Response

204

Cancel Trade Offer

Route

POST {gameId}/trade/player/cancel

Success Response

204

Play Soldier Card

Route

POST {gameId}/play-growth-card/soldier

Success Response

204

Play Gatherer Card

Route

POST {gameId}/play-growth-card/gatherer

Request Body

{
  "resource": 3
}
  • resource - ResourceType

Success Response

204

Play Roaming Card

Route

POST {gameId}/play-growth-card/roaming

Success Response

204

Play Wealth Card

Route

POST {gameId}/play-growth-card/wealth

Request Body

{
  "firstResource": 3,
  "secondResource": 4
}
  • firstResource - ResourceType
  • secondResource - ResourceType

Success Response

204