Web Panel WebSocket API


#1

An API is provided to allow for database queries, updates and deletes as well as command execution via WebSockets. This API uses JSON data for accepting and returning data.

API End Point
The API is provided on the server that PhantomBot runs from on the baseport plus 4. For example, if the bot runs on localhost and port 25000, the API end point will be:

http://localhost:25004

Authentication
To authenticate to the WebSocket an authentication JSON package must be sent first. This is in the format:

{ 
	"authenticate" : "authentication_key"
}

Where authentication_key is the webauth key from the botlogin.txt file.

Authentication Return
If authentication fails then the following is returned, and will be returned to any additional calls on the WebSocket:

{ 
	"autherror" : "not authenticated"
}

Query DB
To query the DB for a specific key value, use the following JSON request:

{
	"dbquery" : "unique_id", 
	"query" : { 
		"table" : "table_name", 
		"key" : "key_name" 
	} 
}

Query DB Return
The WebSocket will return a JSON object:

{
	"query_id" : "unique_id", 
	"result" : { 
		"table" : "table_name",
		"key_name" : "value" 
	} 
}

If there is an error:

{ 
	"query_id" : "unique_id", 
	"error" : "error" 
}

Query DB Keys and Values
To query the DB for all keys and values from a table:

{ 
	"dbkeys" : "unique_id", 
	"query" : { 
		"table" : "table_name"  
	}
}

Query DB Keys and Values for Multiple Tables
To query the DB for all keys and values from multiple tables:

{
	"dbkeyslist" : "unique_id",
	"query" : [
		{ 
			"table" : "table_name1"
		},
		{
			"table" : "table_name2"
		}
	]
}

Query DB Keys and Values Return
The WebSocket will return the following:

{ 
	"query_id" : "unique_id", 
	"results" : [
		{ 
			"table" : "table_name", 
			"key" : "key_name", 
			"value" : "value" 
		}
	]
}

In the event of an error:

{ 
	"query_id" : "unique_id", 
	"error" : "error" 
}

Update DB
To update, or set, a value in the DB:

{ 
	"dbupdate" : "unique_id", 
	"update" : { 
		"table" : "table_name", 
		"key" : "key_name", 
		"value" : "new_value" 
	}
}

Update DB Return
The WebSocket will return the following:

{ 
	"query_id" : "unique_id" 
}

Delete from DB
To delete a key and value pair from the DB:

{ 
	"dbdelkey" : "unique_id", 
	"delkey" : { 
		"table" : "table_name", 
		"key" : "key_name"
	} 
}

Delete from DB Return
The WebSocket will return the following:

{ 
	"query_id" : "unique_id"
}

Execute a Command
To execute a command in PhantomBot. The username and query_id fields are optional. username indicates a user to run the command as which defaults to the PhantomBot account. query_id allows for tracking of the command, and will return upon completion of the action - however, this does not indicate nor represent if the command was successful or not:

{ 
	"command" : "command line",
	"username" : "user name",        // Optional
	"query_id" : "unique_id"         // Optional
}

Optional Command Execution Return
If a query_id was provided then the following is returned:

{
	"query_id" : "unique_id"
}

Unique ID and Purpose
As it is possible to utilize the WebSocket in an environment, such as JavaScript, which makes a WebSocket call and then moves and does not wait for a return value, the WebSocket requests a unique ID be included with all DB requests that will be returned as part of the response packet.


API Site creation
Intergrations? (Website)
Setting user points remotely by command line, HTTP, or API
Websocket API Python Script
Writing to phantombot.db with 3rd Party Program
Two suggestions to make custom commands/APIs work better
Points Leaderboard?
Websocket alerts based on the Observer Design Pattern