Codebreaker Solitaire API Guide

What is Codebreaker?

Codebreaker is a simple game of deductive reasoning---a more generalized variant of the board game Mastermind and the earlier pencil-and-paper game Bulls and Cows---implemented as a RESTful service that permits clients (consumers of the service) to present the game to users for play.

Rules of play

These are the rules of play for a generalized form of Bulls and Cows, stated in a form suitable for playing with pencil and paper.

Players

There are 2 roles in the game: codemaker and codebreaker. In the pencil-and-paper and board game variants, players typically alternate playing these roles.

Sequence of play

Codemaker: Create the code

To play the game, the codemaker and codebreaker first agree on a code length and pool of characters.

Next, the codemaker generates the code, using only characters in the pool (any given character in the pool may be used more than once), and keeps it secret.

Codebreaker: Crack the code

The objective of the codebreaker in the game is to learn the secret code created by the codemaker, using as few guesses as possible.

Codebreaker: Make a guess

Each guess consists of a string of characters, with length equal to that of the code, and made up only of characters found in the pool used when creating the code.

Codebreaker: Evaluate the guess

When a guess is submitted, the codemaker compares it to the code, and responds to the codebreaker with 2 numbers:

Exact matches

The number of characters in the code that are matched exactly by the characters in the corresponding positions of the guess.
Near matches

The number of characters in the code that aren’t matched exactly by the corresponding characters in the guess, but are matched by characters in the guess in non-corresponding positions.

Any character, in either the code or the guess, can only be used once when counting matches. That is, a corresponding pair of characters in the code and guess that form an exact match can’t be used in any near matches, and any character used in one near match can’t be used in any others.

Codebreaker: Refine the guess

Using the codemaker’s response to the most recent guess, along with responses to any previous guesses (if any), the codebreaker refines the guess---after which the codemaker evaluates the new guess and tells the codebreaker the counts of exact and near matches, the codebreaker refines the guess, and so on.

End of play

A single game ends when the codebreaker successfully guesses the code.

Typically, players will play multiple games, alternating roles, and keeping a tally of the total number of guesses for each player. After an agreed-upon number of games, the player with the lowest guess tally wins.

Example game

Creating the code

The codemaker and codebreaker agree on a pool of characters of "A", "B", "C", and "D", with a code length of 3.
The codemaker creates (randomly or otherwise) a secret code---a sequence of 3 characters, all of which must be in the pool. In this case, assume the generated secret code is "BDC".

Cracking the code

For the first attempt, the codebreaker (in this example) guesses "AAA".
Since none of the characters in the guess match (exactly or nearly) characters in the code, the codemaker tells the codebreaker that there are 0 exact matches and 0 near matches.
The codebreaker now knows that the code contains no "A" characters, and guesses "BBB" for the next attempt.
The codemaker responds that the guess has 1 exact match (the "B" in the first position of the guess matches the "B" in the first position of the code), and 0 near matches. (Note that the codemaker only reports the counts, not the specific characters or positions that were included in the counts.)
The codebreaker knows that the code contains exactly 1 "B", and chooses "BCC" for the next guess.
This time, the codemaker counts 2 exact matches (the "B" in the first position and the "C" in the third position) and 0 near matches.
The codebreaker knows from the previous guess that 1 of the matches is "B"; since there are only exact matches in the current guess, the first character of the code must be "B". The code also contains exactly 1 "C", but it might be in the second or third position. Taking a chance, the codebreaker guesses "BCD".
Neither the "C" nor the "D" in the guess match the code exactly, but both count as near matches. So the codemaker reports 1 exact match ("B" in the first position) and 2 near matches ("C" and "D").
The codebreaker has figured it out now: Since the "B" in the first position is an exact match (deduced in steps 5 & 7), and there are 2 near matches, the "C" and "D" have to be swapped, for a guess of "BDC".
The codemaker examines the guess and sees that all 3 characters match the code exactly. With 3 exact matches after 5 guesses, the code has been guessed correctly, so the game is over.

Service

Overview

The Codebreaker Solitaire service acts as the codemaker, with endpoints allowing a client (in the codebreaker role) to start, retrieve, and delete games, and to submit and retrieve guesses.

Since the service is always the codemaker, and since the service provides no capabilities to compare a given codebreaker’s performance against that of any other codebreaker using the service, it is best suited to solitaire play: A client application would make requests of the service to start games and submit guesses on behalf of a user; an indefinite number of games could be played in this fashion, presumably with the aim of improving the user’s deductive reasoning skills.

Disclaimer

Since the service is developed and maintained for use in the Deep Dive Coding curriculum, we reserve the right to change the specifications below without warning, at any time. This service is intended to be used for educational purposes only, and is made available on an as-is basis, without warranties or conditions of any kind, either express or implied.

Basic specifications

The service does not require authentication or an API key.
All requests that include body content are expected to send that content as JSON, accompanied by the Content-type: application/json header.
If the request includes an Accept header, it must include application/json, application/*, or */* in the list of acceptable content types.
All non-empty response bodies returned by the service are also JSON, also with the Content-type: application/json header.
Every 24 hours, inactive games are removed from the database. An inactive game is defined as one which has had no guesses submitted in the last 14 days.

Endpoints

Start new game

Request

POST /codebreaker-solitaire/games

Starts a new game, randomly generating a secret code using the properties specified in the request body.

Body

Type Description

Type	Description
`Game`	Code generation settings.

Game

Code generation settings.

Responses

Status Body Description

Status	Body	Description
201 Created	`Game`	Code generated & game started successfully.
400 Bad Request	`Error`	Invalid code length or character pool.

201 Created

Game

Code generated & game started successfully.

400 Bad Request

Error

Invalid code length or character pool.

Example

Request

POST /codebreaker-solitaire/games HTTP/1.1
Content-Type: application/json
Content-Length: 42
Host: ddc-java.services

{
  "pool" : "ABCDEF",
  "length" : 4
}

Response

HTTP/1.1 201 Created
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Location: https://ddc-java.services/codebreaker-solitaire/games/PQHV4YfiRlOUTeOWfWdojw
Content-Type: application/json
Content-Length: 167

{
  "id" : "PQHV4YfiRlOUTeOWfWdojw",
  "created" : "2024-01-26T01:49:11.623+00:00",
  "pool" : "ABCDEF",
  "length" : 4,
  "solved" : false,
  "guesses" : [ ]
}

Retrieve a game

Request

GET /codebreaker-solitaire/games/{gameId}

Returns the game with the unique identifier specified by gameId.

Path parameters

Parameter Description

Parameter	Description
`gameId`	Unique identifier of game resource.

gameId

Unique identifier of game resource.

Responses

Status Body Description

Status	Body	Description
200 OK	`Game`	Specified game returned.
404 Not Found	`Error`	No game exists with an `id` equal to the specified `gameId`.

200 OK

Game

Specified game returned.

404 Not Found

Error

No game exists with an id equal to the specified gameId.

Example

Request

GET /codebreaker-solitaire/games/b2NTC168RMWV5YRk8XZmcQ HTTP/1.1
Host: ddc-java.services

Response

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
Content-Length: 357

{
  "id" : "b2NTC168RMWV5YRk8XZmcQ",
  "created" : "2024-01-26T01:49:12.031+00:00",
  "pool" : "ABCDEF",
  "length" : 4,
  "solved" : false,
  "guesses" : [ {
    "id" : "iAjtYQcEQEShxrRHnafCHA",
    "created" : "2024-01-26T01:49:12.038+00:00",
    "text" : "FEDC",
    "exactMatches" : 0,
    "nearMatches" : 2,
    "solution" : false
  } ]
}

Submit a guess

Request

POST /codebreaker-solitaire/games/{gameId}/guesses

Submits a guess against the game specified by gameId.

Path parameters

Parameter Description

Parameter	Description
`gameId`	Unique identifier of game resource.

gameId

Unique identifier of game resource.

Body

Type Description

Type	Description
`Guess`	Text of guess.

Guess

Text of guess.

Responses

Status Body Description

Status	Body	Description
201 OK	`Guess`	Guess submitted successfully.
400 Bad Request	`Error`	Length of guess doesn’t match code length.
404 Not Found	`Error`	No game exists with an `id` equal to the specified `gameId`.
409 Conflict	`Error`	The game with the specified `gameId` is already completed; that is, the code has been guessed correctly.

201 OK

Guess

Guess submitted successfully.

400 Bad Request

Error

Length of guess doesn’t match code length.

404 Not Found

Error

No game exists with an id equal to the specified gameId.

409 Conflict

Error

The game with the specified gameId is already completed; that is, the code has been guessed correctly.

Example

Request

POST /codebreaker-solitaire/games/__TGExR1Qq-Faf_qBOeOLg/guesses HTTP/1.1
Content-Type: application/json
Content-Length: 25
Host: ddc-java.services

{
  "text" : "AABBCC"
}

Response

HTTP/1.1 201 Created
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Location: https://ddc-java.services/codebreaker-solitaire/games/__TGExR1Qq-Faf_qBOeOLg/guesses/1nr_rvCKQcKL0Z6PhA7kTQ
Content-Type: application/json
Content-Length: 177

{
  "id" : "1nr_rvCKQcKL0Z6PhA7kTQ",
  "created" : "2024-01-26T01:49:12.449+00:00",
  "text" : "AABBCC",
  "exactMatches" : 1,
  "nearMatches" : 4,
  "solution" : false
}

Retrieve a guess

Request

GET /codebreaker-solitaire/games/{gameId}/guesses/{guessId}

Returns the guess with the unique identifier guessId submitted in the game identified by gameId.

Path parameters

Parameter Description

Parameter	Description
`gameId`	Unique identifier of game resource.
`guessId`	Unique identifier of guess resource.

gameId

Unique identifier of game resource.

guessId

Unique identifier of guess resource.

Responses

Status Body Description

Status	Body	Description
200 OK	`Guess`	Specified guess returned.
404 Not Found	`Error`	No game exists with an `id` equal to the specified `gameId`, no guess identified by `guessId` exists, or guess identified by `guessId` is not associated with game identified by `gameId`.

200 OK

Guess

Specified guess returned.

404 Not Found

Error

No game exists with an id equal to the specified gameId, no guess identified by guessId exists, or guess identified by guessId is not associated with game identified by gameId.

Example

Request

GET /codebreaker-solitaire/games/jrGCni6eTUqybpT6Zrr0QA/guesses/MtSaHMjDT_yZCOLM2gVH2Q HTTP/1.1
Host: ddc-java.services

Response

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
Content-Length: 175

{
  "id" : "MtSaHMjDT_yZCOLM2gVH2Q",
  "created" : "2024-01-26T01:49:12.339+00:00",
  "text" : "AAAA",
  "exactMatches" : 0,
  "nearMatches" : 0,
  "solution" : false
}

Delete a game

Request

DELETE /codebreaker-solitaire/games/{gameId}

Deletes the game (and all related guesses) with the unique identifier gameId.

Path parameters

Parameter Description

Parameter	Description
`gameId`	Unique identifier of game resource.

gameId

Unique identifier of game resource.

Responses

Status Body Description

Status	Body	Description
204 No Content	(none)	Specified game deleted.
404 Not Found	`Error`	No game exists with an `id` equal to the specified `gameId`.

204 No Content

(none)

Specified game deleted.

404 Not Found

Error

No game exists with an id equal to the specified gameId.

Example

Request

DELETE /codebreaker-solitaire/games/-Mp0wJ-dRaaOSE8gsaYTSA HTTP/1.1
Host: ddc-java.services

Response

HTTP/1.1 204 No Content
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers

Schemas

`Game`

`POST` request body

Path Type Description

Path	Type	Description
`pool`	`String`	Pool of available characters for code and guesses. Duplicated characters will be ignored. Null or unassigned characters (i.e. code point values not mapped to a Unicode character) are not allowed.
`length`	`Number`	Length (in characters) of generated code. Valid range is 1 to 20.

pool

String

Pool of available characters for code and guesses. Duplicated characters will be ignored. Null or unassigned characters (i.e. code point values not mapped to a Unicode character) are not allowed.

length

Number

Length (in characters) of generated code. Valid range is 1 to 20.

`GET` & `POST` response body

Path Type Description

Path	Type	Description
`id`	`String`	Unique identifier of the game.
`created`	`String`	Timestamp of code creation (start of game).
`pool`	`String`	Pool of available characters for code (and guesses).
`length`	`Number`	Length (in characters) of generated code.
`solved`	`Boolean`	Flag indicating whether code has been guessed successfully.
`text`	`String`	Text of secret code. This is only included in responses for completed (solved) games.
`guesses`	`Guess[]`	Array of guesses submitted in this game.

id

String

Unique identifier of the game.

created

String

Timestamp of code creation (start of game).

pool

String

Pool of available characters for code (and guesses).

length

Number

Length (in characters) of generated code.

solved

Boolean

Flag indicating whether code has been guessed successfully.

text

String

Text of secret code. This is only included in responses for completed (solved) games.

guesses

Guess[]

Array of guesses submitted in this game.

`Guess`

`POST` request body

Path Type Description

Path	Type	Description
`text`	`String`	Guess of code text.

text

String

Guess of code text.

`GET` & `POST` response body

Path Type Description

Path	Type	Description
`id`	`String`	Unique identifier of the submitted guess.
`created`	`String`	Timestamp of guess submission.
`text`	`String`	Text of guess.
`exactMatches`	`Number`	Count of characters in the guess that are in the same positions in the secret code.
`nearMatches`	`Number`	Count of characters in the guess that are in secret code, but not in the same positions.
`solution`	`Boolean`	Flag indicating whether this guess exacly matches the secret code.

id

String

Unique identifier of the submitted guess.

created

String

Timestamp of guess submission.

text

String

Text of guess.

exactMatches

Number

Count of characters in the guess that are in the same positions in the secret code.

nearMatches

Number

Count of characters in the guess that are in secret code, but not in the same positions.

solution

Boolean

Flag indicating whether this guess exacly matches the secret code.

`Error`

Path Type Description

Path	Type	Description
`timestamp`	`String`	Timestamp of request.
`status`	`Number`	HTTP response status code.
`error`	`String`	HTTP response status text.
`message`	`String`	Additional error message.
`path`	`String`	Host-relative URL of request.
`details`	`Object`	Additional details, generally included with validation errors.

timestamp

String

Timestamp of request.

status

Number

HTTP response status code.

error

String

HTTP response status text.

message

String

Additional error message.

path

String

Host-relative URL of request.

details

Object

Additional details, generally included with validation errors.

Credits, copyrights, and licenses

Codebreaker

The source code and documentation of Codebreaker were written by Nicholas Bennett.

Documentation

Source code

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Spring Framework, Spring Boot, Spring Data, Spring HATEOAS, Spring REST Docs

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Hibernate ORM

Licensed under the GNU Lesser General Public License, version 2.1. You can find a copy of this license at https://www.gnu.org/licenses/lgpl-2.1.en.html