deduce-api

(No, really. It's a game)

Introduction

Welcome to the landing page for deduce-api, a free, open-source RESTful web service API implementation of a game ruleset. The API is intended to be used as an educational tool, allowing developers to either attempt programmatic or algorithmic solution of the game, or the implementation of user interfaces allowing interactive play, or any other creative implementation you can think of.

The server is (hopefully) currently running and available publicly on port 8080 on this domain (deduce-api.ws). You can implement any client code you like to access the public instance, or you can download the server code from the GitHub repository and run it locally.

There is also a reference algorithmic client implementation available here. This client is written in Node.js, and demonstrates a naive or "brute-force" solution with a best-case scenario of 22 steps to solve. Surely you can find a more clever algorithm.

There is a server status page here so you can check to see if the public api is currently running.

Rules

The point of the game is to apply deductive reasoning in order to solve a secret word puzzle in a manner vaguely similar to a famous pen-and-paper game commonly known as Hangman. Once a player begins a game, it is known as a match. A match begins with the selection of a secret word. The player's task is to deduce the word by asking questions about letters. Secret words must adhere to a set of criteria. Each word must be exactly five letters long, and contain no repeated letters. For the sake of this project, valid words are taken from the official ENABLE Word List project, used by such prominent word games as Scrabble and Words With Friends.

Once a secret word is selected, the letters composing the word are removed from the alphabet, creating a subset. The player then asks which letters remain in the subset one at a time by naming indexes. For example, "what is the letter at index 0?" would be a valid question. If the answer to that question is "A" then the player knows that the letter A is not used in the secret word. If the answer to that question is "C" then the player may deduce that both letters A and B are in the secret word, and may begin solving the puzzle by asking further questions and thinking through anagrams of known letters. The challenge is to solve the puzzle as quickly as possible. A player may not attempt consecutive solutions, an incorrect solution attempt must be followed by an index inquiry prior to a subsequent solution attempt.

The complete list of all possible words is available through the API. This will help with algorithmic solutions.

That's it! Simple rules, but tricky thinking.

Endpoints

When using the public API, all endpoints are relative to the base URL http://deduce-api.ws:8080

There is a WADL file documenting service endpoints available here.

All deduce-api endpoints return data as JSON. Response bodies represent a response entity wrapper, containing status and message values for indicating successful or erroneous invocations, along with an entity. The entity will vary based on the endpoint. The one exception is the listValidWords endpoint, which returns only a JSON list of words.

• POST /deduceMatch/createMatch

  Creates a new match, returning the match details, including match id, which will be used for subsequent operations.

  example response:

  Content-Length →246
  Content-Type →application/json
  Date →Thu, 08 Sep 2016 02:46:37 GMT
  Location →http://localhost:8080/57d0d10d85770e0319119843/details
  
  {
  	"status": "CREATED",
  	"message": "Match created: http://localhost:8080/57d0d10d85770e0319119843/details",
  	"entity": {
  			"id": "57d0d10d85770e0319119843",
  			"solution": "[UNSOLVED]",
  			"isSolved": false,
  			"events": []
  	
  }
  						

• GET /deduceMatch/{match_id}/details

  Returns details for the specified match.

  Example response:

  Content-Length →179
  Content-Type →application/json
  Date →Thu, 08 Sep 2016 02:50:35 GMT
  
  {
  	"status": "OK",
  	"message": "Match found",
  	"entity": {
  		"id": "57d0d10d85770e0319119843",
  		"solution": "[UNSOLVED]",
  		"isSolved": false,
  		"events": []
  	}
  }
  						

• GET /deduceMatch/{match_id}/letterAtIndex/{index}

  Returns the letter at specified index within the alphabet subset for the specified match. This also adds an event to the match details.

  Example response:

  Content-Length →64
  Content-Type →application/json
  Date →Thu, 08 Sep 2016 03:00:23 GMT
  					  
  {
  	"status": "OK",
  	"message": "Success",
  	"entity": "P"
  }
  						

• PUT /deduceMatch/{match_id}/solve/{solution}

  Returns match details, which will indicate successful or unsuccessful solution attempt. This also adds an event to the match details.

  Example response:

  Content-Length →437
  Content-Type →application/json
  Date →Thu, 08 Sep 2016 03:11:42 GMT
  					  
  {
  	"status": "OK",
  	"message": "Solution Incorrect",
  	"entity": {
  		"id": "57d0d10d85770e0319119843",
  		"solution": "[UNSOLVED]",
  		"isSolved": false,
  		"events": [
  			{
  				"eventName": "LETTER_AT_INDEX",
  				"details": "index: 12 - letter: P",
  				"date": "Wed Sep 07 22:00:23 CDT 2016"
  			},
  			{
  				"eventName": "SOLUTION_ATTEMPT",
  				"details": "BLUES",
  				"date": "Wed Sep 07 22:11:42 CDT 2016"
  			}
  		]
  	}
  }
  						

• GET /listValidWords

  Returns a list of all valid words fitting the criteria for consideration.

  Example response:

  Content-Type →application/json
  Date →Thu, 08 Sep 2016 03:15:11 GMT
  Transfer-Encoding →chunked
  					  
  {
  	"status": "OK",
  	"message": "SUCCESS: Words list found.",
  	"entity": {
  		"id": "581932f909db5a75a65a814e",
  		"words": [
  		"DUSKY",
  		"HOCUS",
  		"QUICK",
  		"GRANT",
  		"OCTAD",
  		...
  		]
  }
  						

Example match

The following steps demonstrate how a full match might be played. We begin by creating a match.

• POST /deduceMatch/createMatch

  Content-Length →246
  Content-Type →application/json
  Date →Thu, 08 Sep 2016 02:46:37 GMT
  Location →http://localhost:8080/57d0d10d85770e0319119843/details
  					
  {
  	"status": "CREATED",
  	"message": "Match created: http://localhost:8080/57d0d10d85770e0319119843/details",
  	"entity": {
  		"id": "57d0d10d85770e0319119843",
  		"solution": "[UNSOLVED]",
  		"isSolved": false,
  		"events": []
  	}
  }
  						

We will now use the match id 57d0d10d85770e0319119843 for all subsequent actions on this match. For the next step, let's see what letter exists at index 0.

• GET /deduceMatch/57d0d10d85770e0319119843/letterAtIndex/0

  Content-Length →64
  Content-Type →application/json
  Date →Thu, 08 Sep 2016 03:00:23 GMT
  					  
  {
  	"status": "OK",
  	"message": "Success",
  	"entity": "C"
  }
  						

Note that the letter at index 0 is C. This means both letters A and B are in the secret word. We now know 2 of the five letters in the word. Since five letters have been removed from the alphabet, there are 21 letters in the subset. So our known picture of the subset is as below.

0	1	2	3	4	5	6	7	8	9	10	11	12	13	14	15	16	17	18	19	20
C

An algorithmic client can begin applying logic to the words list using the two known letters to narrow the possible solutions down. But for now, let's just assume interactive play and try a different index inquiry. Lets try index 10.

• GET /deduceMatch/57d0d10d85770e0319119843/letterAtIndex/10

  Content-Length →64
  Content-Type →application/json
  Date →Thu, 08 Sep 2016 03:00:23 GMT
  					  
  {
  	"status": "OK",
  	"message": "Success",
  	"entity": "M"
  }
  						

If you start with letter C on index 0, and count forward to index 10, you find that letter M is the expected value. This means that none of the letters between C and M are in the secret word. This deductive conclusion allows us to fill in much of the known subset, making the word much easier to guess.

0	1	2	3	4	5	6	7	8	9	10	11	12	13	14	15	16	17	18	19	20
C	D	E	F	G	H	I	J	K	L	M

Now let's check on index 15.

• GET /deduceMatch/57d0d10d85770e0319119843/letterAtIndex/15

  Content-Length →64
  Content-Type →application/json
  Date →Thu, 08 Sep 2016 03:00:23 GMT
  					  
  {
  	"status": "OK",
  	"message": "Success",
  	"entity": "U"
  }
  						

Interesting. The letter at index 15 is U. The letter U is eight places past the letter M in the full alphabet. This means that three of those seven in-between letters are in our secret word. We already know two of the letters in the word, so this tells us quite a bit. First let's fill in our known subset table. Because we know the remaining three letters all exist between M and U, then none of the letters after U are in the secret word.

0	1	2	3	4	5	6	7	8	9	10	11	12	13	14	15	16	17	18	19	20
C	D	E	F	G	H	I	J	K	L	M	?	?	?	?	U	V	W	X	Y	Z

So the letters in our secret word could be expressed as A, B, [N|O|P|Q|R|S|T], [N|O|P|Q|R|S|T], [N|O|P|Q|R|S|T]. Perhaps a regular expression could help? Wait, we're doing this with our minds, so we'll carry on and try zeroing in on some letters. Let's look at index 12.

• GET /deduceMatch/57d0d10d85770e0319119843/letterAtIndex/12

  Content-Length →64
  Content-Type →application/json
  Date →Thu, 08 Sep 2016 03:00:23 GMT
  					  
  {
  	"status": "OK",
  	"message": "Success",
  	"entity": "P"
  }
  						

The letter at index 12 is P. Since index 10 is M, this means that either N or O is in our secret word. This also lets us fill in the table a bit more.

0	1	2	3	4	5	6	7	8	9	10	11	12	13	14	15	16	17	18	19	20
C	D	E	F	G	H	I	J	K	L	M	?	P	?	?	U	V	W	X	Y	Z

This means our letters list looks a bit different: A, B, [N|O], [Q|R|S|T], [Q|R|S|T]. We're getting closer! Lets look at index 14.

• GET /deduceMatch/57d0d10d85770e0319119843/letterAtIndex/14

  Content-Length →64
  Content-Type →application/json
  Date →Thu, 08 Sep 2016 03:00:23 GMT
  					  
  {
  	"status": "OK",
  	"message": "Success",
  	"entity": "S"
  }
  						

Ah ha! Index 14 is S. This gives us even more information. Lets look at the table.

0	1	2	3	4	5	6	7	8	9	10	11	12	13	14	15	16	17	18	19	20
C	D	E	F	G	H	I	J	K	L	M	?	P	?	S	U	V	W	X	Y	Z

Index 14 is S and index 15 is U. So now we know the letter T is in our word. So now our known letters list look like this: A, B, [N|O], [Q|R|S], T.

Maybe the word is BOAST!

• PUT /deduceMatch/57d0d10d85770e0319119843/solve/BOAST

  Content-Length →437
  Content-Type →application/json
  Date →Thu, 08 Sep 2016 03:11:42 GMT
  					  
  {
  	"status": "OK",
  	"message": "Solution Incorrect",
  	"entity": {
  		"id": "57d0d10d85770e0319119843",
  		"solution": "[UNSOLVED]",
  		"isSolved": false,
  		"events": [
  			{
  				"eventName": "LETTER_AT_INDEX",
  				"details": "index: 0 - letter: C",
  				"date": "Wed Sep 07 22:00:23 CDT 2016"
  			},
  			{
  				"eventName": "LETTER_AT_INDEX",
  				"details": "index: 10 - letter: M",
  				"date": "Wed Sep 07 22:00:23 CDT 2016"
  			},
  			{
  				"eventName": "LETTER_AT_INDEX",
  				"details": "index: 15 - letter: U",
  				"date": "Wed Sep 07 22:00:23 CDT 2016"
  			},
  			{
  				"eventName": "LETTER_AT_INDEX",
  				"details": "index: 12 - letter: P",
  				"date": "Wed Sep 07 22:00:23 CDT 2016"
  			},
  			{
  				"eventName": "LETTER_AT_INDEX",
  				"details": "index: 14 - letter: S",
  				"date": "Wed Sep 07 22:00:23 CDT 2016"
  			},
  			{
  				"eventName": "SOLUTION_ATTEMPT",
  				"details": "BOAST",
  				"date": "Wed Sep 07 22:11:42 CDT 2016"
  			}
  		]
  	}
  }
  						

The word is not BOAST! But lets look at the results of that solution attempt. You see it has each of the actions we have performed so far in the match details. This lets us count our steps to see how efficient we are. So far we've taken 6 steps, and our table only has two empty spots left. Thus is the power of deduction. We could continue to make subsequent guesses, but the game rules require us to make an index query prior to more solution attempts. So, lets pick one of the two remaining unknown indexes, lets try 11.

• GET /deduceMatch/57d0d10d85770e0319119843/letterAtIndex/11

  Content-Length →64
  Content-Type →application/json
  Date →Thu, 08 Sep 2016 03:00:23 GMT
  					  
  {
  	"status": "OK",
  	"message": "Success",
  	"entity": "N"
  }
  						

So the letter at index 11 is N. Because we know index 12 is P, this tells us that the letter O is in our word. But more importantly, it allows us to make another solution attempt. We probably don't need the table as much anymore, at this point we know the letters are A, B, O, [Q|R|S], T. Is the word ABORT?

• PUT /deduceMatch/57d0d10d85770e0319119843/solve/ABORT

  Content-Length →437
  Content-Type →application/json
  Date →Thu, 08 Sep 2016 03:11:42 GMT
  					  
  {
  	"status": "OK",
  	"message": "Success",
  	"entity": {
  		"id": "57d0d10d85770e0319119843",
  		"solution": "ABORT",
  		"isSolved": true,
  		"events": [
  			{
  				"eventName": "LETTER_AT_INDEX",
  				"details": "index: 0 - letter: C",
  				"date": "Wed Sep 07 22:00:23 CDT 2016"
  			},
  			{
  				"eventName": "LETTER_AT_INDEX",
  				"details": "index: 10 - letter: M",
  				"date": "Wed Sep 07 22:00:23 CDT 2016"
  			},
  			{
  				"eventName": "LETTER_AT_INDEX",
  				"details": "index: 15 - letter: U",
  				"date": "Wed Sep 07 22:00:23 CDT 2016"
  			},
  			{
  				"eventName": "LETTER_AT_INDEX",
  				"details": "index: 12 - letter: P",
  				"date": "Wed Sep 07 22:00:23 CDT 2016"
  			},
  			{
  				"eventName": "LETTER_AT_INDEX",
  				"details": "index: 14 - letter: S",
  				"date": "Wed Sep 07 22:00:23 CDT 2016"
  			},
  			{
  				"eventName": "SOLUTION_ATTEMPT",
  				"details": "BOAST",
  				"date": "Wed Sep 07 22:11:42 CDT 2016"
  			},
  			{
  				"eventName": "LETTER_AT_INDEX",
  				"details": "index: 11 - letter: N",
  				"date": "Wed Sep 07 22:00:23 CDT 2016"
  			},
  			{
  				"eventName": "SOLUTION_ATTEMPT",
  				"details": "ABORT",
  				"date": "Wed Sep 07 22:11:42 CDT 2016"
  			}
  		]
  	}
  }
  						

Success! We solved the puzzle in eight steps. Less than half the minimum number of steps required by the brute-force algorithmic reference client.

Hopefully after this exercise you understand how to use the deduce-api service, and feel inspired to write interesting client implementations in your favorite programming languages.

Project by illingtonFlex