scrabble

A spring boot application that is setup to be a perfect scrabble game application.

requirements

• MySQL 5.6.19+
• Java/JRE 1.8+
• Maven 3.5.3+

setup

Before running the application MySQL needs to be setup. Install MySQL and create an user "root" with no password. Give the "root" user the permission to create/remove tables.
Create the following databases:

• scrabble_db
• scrabble_db_test

Make sure MySQL is running in port 3306 before the application starts.

run application

Because the application needs to setup the initial database, the command to run the first time is different than the subsequent runs. Make sure to change directory to the scrabble project folder before running the commands.

• Run application first time
  mvn spring-boot:run -Dspring-boot.run.arguments=--spring.datasource.initialization-mode=always
• Run application after first time
  mvn spring-boot:run

Once the application is run for the first time, it creates four test users by default with user id 1, 2, 3 and 4.

run tests

Because the integration tests in the application needs to setup the initial database, the command to run the tests first time is different than the subsequent runs. Make sure to cd to the scrabble project folder before running the commands.

• Run test first time
  mvn test -D --spring.datasource.initialization-mode=always
• Run test after first time
  mvn test

dictionary

The application currently is setup to work with a SOWPODS and TWL06 dictionary. Both dictionary words are loaded by default when the application starts. If you want to load only one dictionary then provide --app.dictionaries command line argument with either one of following values:

• SOWPODS
• TWL06

For example to load only SOWPODS dictionary on first run:
mvn spring-boot:run -Dspring-boot.run.arguments=--spring.datasource.initialization-mode=always,--app.dictionaries=SOWPODS
For subsequent runs:
mvn spring-boot:run -Dspring-boot.run.arguments=--app.dictionaries="SOWPODS"

All words played and the words formed during the play must be in the dictionary. Otherwise, the play is considered invalid.

response JSON objects

person

id - id of the person (integer)
userName - user name of the person (string)
firstName - first name of the person (string)
lastName - last name of the person (string)

{
    "id": 1,
    "userName": "scrabbleUser",
    "firstName": "scrabbler",
    "lastName": "champion"
}

tile

row - row index of the tile. starts from 0 (integer)
column - column index of the tile. starts from 0 (integer)
value - character value of the tile. Empty tiles are represented by '.' (string)
boost - boost value of tile (integer)
charBoost - boost value of character used in tile (integer)

{
    "row": 0,
    "column": 0,
    "value": ".",
    "boost": 1,
    "charBoost": 1
}

board

size - size of board (integer)
tiles - JSON array of Tile JSON objects

{
    "size": 2,
    "tiles": [
        {
            "row": 0,
            "column": 0,
            "value": ".",
            "boost": 1,
            "charBoost": 1
        },
        {
            "row": 0,
            "column": 1,
            "value": ".",
            "boost": 1,
            "charBoost": 1
        },
        {
            "row": 1,
            "column": 0,
            "value": ".",
            "boost": 1,
            "charBoost": 1
        },
        {
            "row": 1,
            "column": 1,
            "value": ".",
            "boost": 1,
            "charBoost": 1
        }
    ]
}

player

person - person JSON object representing the player
order - player order of the person in the game (integer). For example: player who goes first is 1, player who goes second is 2 and so on..

{
    "person": {
        "id": 1,
        "userName": "scrabbleUser",
        "firstName": "scrabbler",
        "lastName": "champion"
    },
    "order": 1
}

game

id - id of the game (integer)
board - board JSON object representing the game
players - JSON array of player JSON objects
state - state of game with integer value of 0 (Initialized), 1 (In progress), 2 (finished)
nextTurnPlayer - player JSON object who makes the move next after the current player

{
    "id": 6,
    "board": {
        "size": 2,
        "tiles": [
            {
                "row": 0,
                "column": 0,
                "value": ".",
                "boost": 1,
                "charBoost": 1
            },
            {
                "row": 0,
                "column": 1,
                "value": ".",
                "boost": 1,
                "charBoost": 1
            },
            {
                "row": 1,
                "column": 0,
                "value": ".",
                "boost": 1,
                "charBoost": 1
            },
            {
                "row": 1,
                "column": 1,
                "value": ".",
                "boost": 1,
                "charBoost": 1
            }
        ]
    },
    "players": [
        {
            "person": {
                "id": 1,
                "userName": "scrabbleUser",
                "firstName": "scrabbler",
                "lastName": "champion"
            },
            "order": 1
        }
    ],
    "state": 0,
    "nextTurnPlayer": {
        "person": {
            "id": 1,
            "userName": "scrabbleUser",
            "firstName": "scrabbler",
            "lastName": "champion"
        },
        "order": 1
    }
}

move

word - the word that was played in the move (string)
row - the row index for the move (integer)
column - the column index for the move (integer)
player - the player JSON object who made the move
direction - the move direction id (integer). 0 for Left to Right and 1 for Top to Bottom.
points - the total points for the move (integer)
time - the long value for the time of the move. Returns the number of milliseconds since January 1, 1970, 00:00:00 GMT.

{
    "word": "test",
    "row": 0,
    "column": 0,
    "player": {
        "person": {
            "id": 1,
            "userName": "scrabbleUser",
            "firstName": "scrabbler",
            "lastName": "champion"
        },
        "order": 1
    },
    "direction": 0,
    "points": 4,
    "time": 1541125957000
}

games

games - JSON array of game JSON object
count - total number of games for the request (integer)
limit - limit specified for the request (integer)
offset - offset specified for the request (integer)

moves

moves - JSON array of move JSON object
count - total number of move for the request (integer)
limit - limit specified for the request (integer)
offset - offset specified for the request (integer)

request JSON objects

player parameter

id - id of the player (integer)
order - player order of the person in the game (integer)

{
    "id": 1,
    "order": 1
}

start game payload JSON object

boardSize - size of the board for the game (integer). Optional and defaults to 15 if not specified.
players - JSON array of player request JSON object. At least one payer request JSON object is required.
tilesPerPlayer - maximum number of tiles for each player for the game. Optional and defaults to square of board size if not specified.

{
    "boardSize": "20",
    "players": [{
    	"id": 1,
    	"order": 1
    }, {
        "id": 2,
        "order": 2
    }],
    "tilesPerPlayer": "100"
}

update game payload JSON object

boardSize - size of the board for the game (integer)
players - JSON array of player request JSON object
state - state of the game (integer). 0 represents initialized (new game), 1 represents in-progress game, 2 represents finished game

{
    "boardSize": "20",
    "players": [{
    	"id": 1,
    	"order": 1
    }, {
        "id": 2,
        "order": 2
    }],
    "state": 0
}

make move payload JSON object

word - the word that the player intends to play for the move (string). Required.
row - the row index of the board from which the word starts (integer). 0 based. Required.
column - the column index of the board from which the word starts (integer). 0 based. Required.
direction - the direction in which the word is played (integer). 0 for left to right. 1 for top to bottom.
player - the player request JSON object representing the player making the move. Required.

{
	"word": "test",
	"row": 0,
	"column": 0,
	"direction": 0,
	"player": {
		"id": 1,
		"order": 1
	}
}

request query parameters

limit - number of results to get at a time (integer). Defaults to 50 for GET calls for collections. Maximum is 500. Defaults to maximum if more that maximum value is specified.
offset - the offset from which the limit applies for the result (integer). Defaults to 0.
state - the state of the game (integer). 0 represents initialized (new game), 1 represents in-progress game, 2 represents finished game.

API's

Purpose	Url	Method	Header	Request Body	Query Parameters	Response Body	Success response	Status Code
Start a new game	/api/1.0/games	POST	Content-Type: application/json	Start game payload JSON object	N/A	Game response JSON object for the game that is created	201
Get list of games	/api/1.0/games	GET	N/A	N/A	limit offset state - Multiple states can be specified as state=0&state=1	Games response JSON object	200
Update a game	/api/1.0/games/{game-id}	PUT	Content-Type: application/json	Update game payload JSON object	N/A	N/A	204
Delete a game	/api/1.0/games/{game-id}	DELETE	N/A	N/A	N/A	204
Get game by id	/api/1.0/games/{game-id}	GET	N/A	N/A	N/A	Game response JSON object for the game with the specified id	200
Make game move	/api/1.0/games/{game-id}/move	POST	Content-Type: application/json	Make move payload JSON Object	N/A	Game response JSON object representing the latest state after the move	200
Get game history	/api/1.0/games/{game-id}/history	GET	N/A	N/A	- limit - offset	Moves response JSON object for the game ordered by move time in ascending order	200