API

REST API

Two main resources:

• Puzzles
• Challenges

Puzzles are the individual puzzles that can be solved. Each is specified with an identifier and contains a starting state.

Challenges are instances of puzzles. There can be multiple instances of the same puzzle being solved. Each challenge tracks the state (board and pieces) of the puzzle separately.

Challenges API

The actions represent operations that can be done on the puzzle. Some puzzles may not be able to be solved without certain actions.

• CLONE
• MOVE
• SWAP
• ROTATE
• PLACE
• REMOVE
• CLEAR
• EVALUATE

POST challenges

Create a challenge for the puzzle identified by puzzleId.

Form parameters:

• puzzleId

The location header of the response will contain the URI to view challenge instance at

POST challenges/{ challengeId }/actions/clone

Clone the challenge to a new instance

The location header of the response will contain the URI to view new challenge instance at

GET challenges/{ challengeId }

JSON view of current state of the challenge

GET challenges/{ challengeId }/view

TEXT view of current state of the challenge

GET challenges/{ challengeId }/viewimage

PNG of current state of the challenge

Query parameters:

• label=true

Specifying the label=true query parameter will have the squares and edges labeled with their identifiers in the image output

DELETE challenges/{ challengeId }

Remove the challenge

POST challenges/{ challengeId }/action/rotate

Rotate piece identified by squareId1 or located at [x1,y1]

Form parameters:

• squareId1
• x1
• y1

The parameter squareId1 takes precedence over x1, y1

The piece does not have to be placed in the board currently (can be unused).

POST challenges/{ challengeId }/action/swap

Swap the piece identified by squareId1 or located at [x1,y1] with the piece identified by squareId2 or located at [x2,y2]

Form parameters:

• squareId1
• x1
• y1
• squareId2
• x2
• y2

The parameters squareId1 and squareId2 take precedence over [x1,y1] and [x2,y2] respectively

Using the identifiers internally calls swap with the [x,y] coordinates of the squares

POST challenges/{ challengeId }/action/move

Move the piece identified by squareId1 or located at [x1,y1] to an adjacent location identified by squareId2, or [x2,y2], or based on specified direction.

Form parameters:

• squareId1
• x1
• y1
• squareId2
• x2
• y2
• direction

direction can be specified with UP, DOWN, RIGHT and LEFT.

The parameters squareId1 and squareId2 take precedence over [x1,y1] and [x2,y2] respectively. direction takes precedence over [x2,y2].

Move must be to an adajacent location x-1, x+1, y-1, or y+1.

POST challenges/{ challengeId }/action/remove

Remove the piece identified by squareId1 or located at [x1,y1] from the board. The piece will now be unused.

Form parameters:

• squareId1
• x1
• y1

The parameter squareId1 takes precedence over [x1,y1].

POST challenges/{ challengeId }/action/place

Place the unused piece identified by squareId1 in the location [x1,y1]. If [x1,y1] is not specified, then the piece will be placed at the first empty spot on the board. First spot is determined by lowest [x,y] location that is empty.

Form parameters:

• squareId1
• x1
• y1

If the piece is already on the board, an error will occur. Pieces must be removed first.

POST challenges/{ challengeId }/action/clear

Remove all squares from the board (all are unused now)

POST challenges/{ challengeId }/action/evaluate

Will provide a JSON response with evaluation report of current state of the challenge. This contains information such as:

• int unusedPiecesCount
• int usedPiecesCount
• int edgeConflictsCount
• int squareConflictsCount
• boolean isFirstSquareA
• boolean solved

Information can be used to progress the challenge through additional actions or know if the challenge is solved.