Xiangqi Cloud Database(aka. "CDB") API has two parts, first is to probe the database, which can be achieved by reqesting CDB's HTTP-based RESTful API.
Then, as an extension to the existing UCI engine protocol, a few new options can be added so that the GUI and the engine can work better when handling results from CDB.
CDB's API access point is: http://www.chessdb.cn/chessdb.php?action=[ACTION]{&[OPTION1]=[VALUE1]...&[OPTIONn]=[VALUEn]}
In which the fields are defined as:
ACTION: Action type, for example, query all known moves (queryall), suggest a move (query / querybest), request analysis (queue), etc.
OPTION & VALUE: Options, for example, position to query (board) and forbidden moves (ban), etc.
Mandatory: board, set to the FEN format encoding of the position to query, e.g. &board=rnbakabnr/9/1c5c1/p1p1p1p1p/9/9/P1P1P1P1P/1C5C1/9/RNBAKABNR w
Optional: ban, set to a list of forbidden moves, separated by "|", e.g. &ban=move:c3c4|move:b2e2|move:c0e2, default is empty, allowing all moves
Optional: showall, set to false if unknown moves should be omitted, e.g. &showall=0 or &showall=1, default is 0, only return known moves
Optional: egtbmetric, set to desired EGTB metric, e.g. &egtbmetric=dtc or &egtbmetric=dtm, default is dtm, using DTM tablebases
Optional: learn, set to whether automatic learning should be enabled, e.g. &learn=0 or &learn=1, default is 1, enabling automatic learning
Return: move data separated by "|", of which each field is separated by ",", fields may contain "move", "score", "rank", "winrate" and "note"
If the position is invalid, "invalid board" is returned, if the position is unknown, "unknown" is returned, if the position is a checkmate or stalemate, "checkmate" or "stalemate" is returned
Mandatory: board, set to the FEN format encoding of the position to query, e.g. &board=rnbakabnr/9/1c5c1/p1p1p1p1p/9/9/P1P1P1P1P/1C5C1/9/RNBAKABNR w
Optional: ban, set to a list of forbidden moves, separated by "|", e.g. &ban=move:c3c4|move:b2e2|move:c0e2, default is empty, allowing all moves
Optional: endgame, set to whether only EGTB data should be returned, e.g. &endgame=0 or &endgame=1, default is 0, all data are returned
Optional: egtbmetric, set to desired EGTB metric, e.g. &egtbmetric=dtc or &egtbmetric=dtm, default is dtm, using DTM tablebases
Optional: learn, set to whether automatic learning should be enabled, e.g. &learn=0 or &learn=1, default is 1, enabling automatic learning
Return: move data separated by "|", of which a normal move are returned as move:[MOVE], an EGTB move is returned as egtb:[MOVE], a candidate move is returned as search:[MOVE]
Candidate moves are a list of moves that may require further processing, such as sending them as "searchmoves" to an engine
If the position is invalid, "invalid board" is returned, if no satisfing move is found, "nobestmove" is returned
Mandatory: board, set to the FEN format encoding of the position to query, e.g. &board=rnbakabnr/9/1c5c1/p1p1p1p1p/9/9/P1P1P1P1P/1C5C1/9/RNBAKABNR w
Optional: ban, set to a list of forbidden moves, separated by "|", e.g. &ban=move:c3c4|move:b2e2|move:c0e2, default is empty, allowing all moves
Optional: egtbmetric, set to desired EGTB metric, e.g. &egtbmetric=dtc or &egtbmetric=dtm, default is dtm, using DTM tablebases
Optional: learn, set to whether automatic learning should be enabled, e.g. &learn=0 or &learn=1, default is 1, enabling automatic learning
Return: CDB's evaluation score of the position, as in eval:[SCORE]
If the position is invalid, "invalid board" is returned, if the position is unknown, "unknown" is returned
Mandatory: board, set to the FEN format encoding of the position to query, e.g. &board=rnbakabnr/9/1c5c1/p1p1p1p1p/9/9/P1P1P1P1P/1C5C1/9/RNBAKABNR w
Optional: ban, set to a list of forbidden moves, separated by "|", e.g. &ban=move:c3c4|move:b2e2|move:c0e2, default is empty, allowing all moves
Optional: egtbmetric, set to desired EGTB metric, e.g. &egtbmetric=dtc or &egtbmetric=dtm, default is dtm, using DTM tablebases
Optional: learn, set to whether automatic learning should be enabled, e.g. &learn=0 or &learn=1, default is 1, enabling automatic learning
Return: CDB's analysis line of the position, as in score:[SCORE],depth:[DEPTH],pv:[MOVE1]{...|[MOVEn]}
If the position is invalid, "invalid board" is returned, if the position is unknown, "unknown" is returned
Mandatory: board, set to the FEN format encoding of the position to query, e.g. &board=rnbakabnr/9/1c5c1/p1p1p1p1p/9/9/P1P1P1P1P/1C5C1/9/RNBAKABNR w
Mandatory: movelist, set to history moves, separated by "|", e.g. &movelist=c3c4|g6g5|h2g2|h7e7, require at least 4 moves
Optional: reptimes, set to the number of allowed repetitions, ranges from 1 to 10, e.g. &reptimes=3, default is 1, adjudicating at the first occuring repetitions
Return: move adjudication status of the final position, separated by "|", as in move:[MOVE],rule:[RESULT]
In which RESULT is the verdict, "none" means no repetition rules apply, "draw" means a repetition draw and "ban" means a forbidden move
If the position is invalid, "invalid board" is returned, if the move list is too short or invalid, "invalid movelist" is returned, if the final position is a checkmate or stalemate, "checkmate" or "stalemate" is returned
Mandatory: board, set to the FEN format encoding of the position to query, e.g. &board=rnbakabnr/9/1c5c1/p1p1p1p1p/9/9/P1P1P1P1P/1C5C1/9/RNBAKABNR w
Return: ok means success
If the position is invalid, "invalid board" is returned, if the position is trivial, nothing is returned
Mandatory: board, set to the FEN format encoding of the position to query, e.g. &board=rnbakabnr/9/1c5c1/p1p1p1p1p/9/9/P1P1P1P1P/1C5C1/9/RNBAKABNR w
Mandatory: move, set to the desired move for analysis, e.g. &move=move:c3c4
Return: ok means success
If the position is invalid, "invalid board" is returned, if the position is trivial, nothing is returned
Usually, only GUIs should send API queries to CDB, engines do not need to make any network queries.
Preferably GUIs can inform the engines about the information returned from CDB via UCI, for example:
While sending "go" commands to engines, append "bookmove [MOVE]" to suggest a move from opening book, engines can decide whether to immediately return "bestmove [MOVE]" or start their own search ignoring the suggestions.
This option is ignored in analysis mode (go infinite) or pondering (go ponder) and must be placed before "searchmoves"
During searches, sending "hint score [SCORE] depth [DEPTH] pv [MOVE1]{... [MOVEn]}" to inform engines about known principal variations.
While sending "go" commands to engines, append "egtbmove [MOVE]" to suggest a move from EGTB, engines can decide whether to immediately return "bestmove [MOVE]" or start their own search ignoring the suggestions.
This option is ignored in analysis mode (go infinite) or pondering (go ponder) and must be placed before "searchmoves"