JSON-RPC:Protocol

The JSON request/responses that UnrealIRCd uses follow the JSON-RPC 2.0 specification.

Request

This is an example query. It calls the channel.list method with empty parameters:

{"jsonrpc": "2.0", "method": "channel.list", "params": {}, "id": 123}

Response

If succesful, UnrealIRCd will reply with a result object. Here's an example if there are 0 channels:

{"jsonrpc": "2.0", "method": "channel.list", "id": 123, "result": {"list": []}}

The result will naturally be different for each method. And as you can see, the id is included so the client application can track request/results.

Error

A request may also result in an error instead of a result object. Here's an example error object that UnrealIRCd may send:

{"jsonrpc": "2.0", "method": "qwerty", "id": 123, "error": {"code": -32601, "message": "Unsupported method"}}

Error codes:

// Official JSON-RPC error codes:
JSON_RPC_ERROR_PARSE_ERROR              = -32700, /**< JSON parse error (fatal) */
JSON_RPC_ERROR_INVALID_REQUEST          = -32600, /**< Invalid JSON-RPC Request */
JSON_RPC_ERROR_METHOD_NOT_FOUND         = -32601, /**< Method not found */
JSON_RPC_ERROR_INVALID_PARAMS           = -32602, /**< Method parameters invalid */
JSON_RPC_ERROR_INTERNAL_ERROR           = -32603, /**< Internal server error */

// UnrealIRCd JSON-RPC server specific error codes:
JSON_RPC_ERROR_API_CALL_DENIED          = -32000, /**< The api user does not have enough permissions to do this call */
JSON_RPC_ERROR_SERVER_GONE              = -32001, /**< The request was forwarded to a remote server, but this server went gone while processing the request */
JSON_RPC_ERROR_TIMEOUT                  = -32002, /**< The request was forwarded to a remote server, but the request/result timed out (15 seconds) */
JSON_RPC_ERROR_REMOTE_SERVER_NO_RPC     = -32003, /**< The request was going to be forwarded to a remote server, but the remote server does not support JSON-RPC */

// UnrealIRCd specific application error codes:
JSON_RPC_ERROR_NOT_FOUND                =  -1000, /**< Target not found (no such nick / channel / ..) */
JSON_RPC_ERROR_ALREADY_EXISTS           =  -1001, /**< Resource already exists by that name (eg on nickchange request, a gline, etc) */
JSON_RPC_ERROR_INVALID_NAME             =  -1002, /**< Name is not permitted (eg: nick, channel, ..) */
JSON_RPC_ERROR_USERNOTINCHANNEL         =  -1003, /**< The user is not in the channel */
JSON_RPC_ERROR_TOO_MANY_ENTRIES         =  -1004, /**< Too many entries (eg: banlist, ..) */
JSON_RPC_ERROR_DENIED                   =  -1005, /**< Permission denied for user (unrelated to api user permissions) */