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.
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