JSON-RPC 2.0 : Console Client

1. Purpose

Quickly query, test and debug JSON-RPC 2.0 applications - this is the purpose of this small Java console client. It has an interactive shell (with readline goodies such as command history) where you can enter JSON-RPC requests and notifications and then view the server's response. The JSON payload of each RPC message can examined if required. To save repeated typing of request ID's there is an option to set a default value for the whole session.

2. Screenshots

Making a JSON-RPC request

A sample JSON-RPC session

Detecting response errors

3. Quick start by example

Download and unzip the application package. Start the client from the command line by pointing your Java runtime (1.5+) to the supplied JAR file and passing the URL of the JSON-RPC 2.0 server as an argument.

java -jar jsonrpc2client.jar http://my-service.net:8080/jsonrpc2/

Once the client starts and is ready, you will be presented with a command prompt where you can enter your JSON-RPC 2.0 requests and notifications

JSON-RPC 2.0 >

To enter a request you must specify the remote method name, the parameters (positional or named, if any) and a request identifier (ID). Here is an example of calling a method that adds two numbers and returns their sum:

JSON-RPC 2.0 > addNumbers [10,20] "req-001"
30

Important: If you omit the request ID (set to "req-001" in the above example) the JSON-RPC standard requires the call to be treated as a notification - and no response is sent back from the server (including errors). If you leave the ID out the client will remind you with a short "[Notification]" message after the command. To save repeated typing of ID's invoke the client with the -a, --auto-id option (see below).

JSON-RPC 2.0 > addNumbers [10,20]
[Notification]

If something goes wrong the client will print an error message. Here is the standard JSON-RPC 2.0 error that servers return if you try to call a method that doesn't exist:

JSON-RPC 2.0 > listNumbers ["one","two","three"] 0
Response [error]: -32601, Method not found

4. Entering requests and notifications, in detail

Request commands have the following format:

method_name [parameters] request_id

Notification commands have the same format as requests, but omit the identifier:

method_name [parameters]

The JSON-RPC standard allows for any string to pose as a method name. However, to simplify the shell commands, this client limits the scope a little. Only method names that conform to the syntax of JavaScript variable names, dotted domains included, are accepted. Some valid examples:

makePayment
addNumbers
_search2
billing.add_account

If the method accepts parameters, whether positional (JSON array of the parameter values) or named (JSON object of the parameter key/value pairs), these are specified in their native JSON format. For example:

[10,20]
{"recipient":"Penny Adams", "amount":175.05}

Request identifiers should be valid JSON scalar values (true, false, number, string). Fractions and null values should be avoided (for the exact reasons check the standard). Here are some valid ID values:

0	     
1	     
"req-001"    
"req-002"    
true

Here is a complete example request command where the remote method is called "makePayment", there are two named parameters to it - "recipient" and "amount", and the identifier is set to 0:

JSON-RPC 2.0 > makePayment {"recipient":"Penny Adams", "amount":175.05} 0

Here is an example command for a notification where the remote method is called "notifyOfProgress" and there's only a single positional number parameter:

JSON-RPC 2.0 > notifyOfProgress [0.75]

For flexibility, the command parser allows the method name, the parameters and the identifier to be entered in any order. Therefore, the following commands are all equivalent:

JSON-RPC 2.0 > addNumbers [10,20] "req-001"    
JSON-RPC 2.0 > addNumbers "req-001" [10,20]    
JSON-RPC 2.0 > "req-001" addNumbers [10,20]    
JSON-RPC 2.0 > "req-001" [10,20] addNumbers    
JSON-RPC 2.0 > [10,20] "req-001" addNumbers    
JSON-RPC 2.0 > [10,20] addNumbers "req-001"

5. Command line arguments

Apart from the mandatory server_URL argument, the client accepts several other options.

java -jar jsonrpc2client.jar [{-a,--auto-id} request_id]
                             [-n,--no-strict] [-v,--verbose]
                             [-h,--help] server_URL

Explanation of the arguments:

Mandatory
`server_URL`	The URL of the remote JSON-RPC 2.0 server.
Optional
`-a,--auto-id request_id`	Specifies a request ID to be appended automatically to each outgoing RPC message. This option can be used to save repeated typing of request ID's in the console.
`-n,--no-strict`	Disables response content type checking (the JSON-RPC standard requires application/json-rpc or application/json HTTP content type header values).
`-v,--verbose`	Causes the program to print the JSON payload of each incoming and outgoing RPC message. Other status information may be printed too.
`-h, --help`	Causes the program to display a short help text about its purpose and usage.

Invocation example specifying a default ID of zero for all requests and turning verbose output on:

java -jar jsonrpc2client -a 0 -v http://192.168.0.2/jsonrpc/

6. Useful tips

6.1 Displaying the JSON content of RPC messages

To view the JSON content of each request, notification and response start the application with the -v option:

java -jar jsonrpc2client -v http://192.168.0.2/jsonrpc/

6.2 Setting a default request ID for the entire session

For each JSON-RPC request you must specify a message identifier. Typing ID's, however, can become tedious after a while. A convenient solution is to start the client with the -a, --auto-id option and specify an ID value to be automatically appended to each outgoing message.

java -jar jsonrpc2client -a 123 http://192.168.0.2/jsonrpc/

The above example sets the ID to 123 (integer). Now you only have to enter the method name and the parameters (if any). The client will then complete the request by appending the preset ID.

Note that with this option you cannot enter notifications. But you can still override the default request ID by specifying an explicit value at the prompt.

6.3 Command history

The client shell features a readline-like interface. One useful goody is the ability to browse through the command history to edit and resend previously entered requests. To do that use the Arrow-Up and Arrow-Down keys.

7. Characteristics

Supported JSON-RPC protocol version: 2.0
RPC transport mechanism: HTTP (POST)
Java Runtime: 1.5+

8. API documentation

The client comes with extensive Java docs if you need to modify or build upon the software.

9. Change log

version 1.0 (2009-12-26)
- First official release
version 1.1 (2010-01-05)
- User friendly messages on bad parameter input
- Remove scalar restriction to positional and named parameters
- Switch to JSON.simple toolkit for parameter parsing
version 1.2 (2010-02-03)
- Upgrades to the latest JSON-RPC 2.0 Base library (version 1.4)
version 1.3 (2010-06-29)
- Correct "application/json-rpc" MIME type detection if a charset is specified at the end of the HTTP Content-Type header
- Upgrades to the latest JSON-RPC 2.0 Base library (version 1.9.1)

10. Useful links

The JSON-RPC 2.0 specification and user group can be found at http://groups.google.com/group/json-rpc.
This client depends on the sister JSON-RPC 2 Base package (also offered here). It provides a base JSON-RPC 2.0 implementation for web apps and services that need to handle the protocol.

11. Download

The JSON-RPC 2.0 client is offered under a paid license, which also allows for access and modification of the source code. To check the license details, price and get the latest version go to the download page.