JSON-RPC 2.0 Shell

  • Interactive RPC shell for rapid querying, testing and
    debugging of JSON-RPC 2.0 web services
  • Pretty formatting of JSON results
  • Browseable request history
  • Auto ID option saves typing

1. A must-have tool for serious JSON-RPC 2.0 development

JSON-RPC 2.0 Shell

The JSON-RPC 2.0 Shell is a neat tool for rapid examination, testing and demonstration of remote JSON-RPC 2.0 web services. Developers will greatly appreciate its time-saving benefits - no more tedious typing of one-off scripts - just point it to the desired server URL and you will be presented with an interactive shell where you can enter your JSON-RPC commands and inspect the responses.

The JSON-RPC 2.0 Shell can be launched from your Windows/ Linux/ Mac OS X CLI and provides typical shell features, such as the ability to browse and edit your JSON-RPC request history. There's also an auto ID option to save typing. And, of course, verbose RPC exception reporting and diagnostics.

All in all, a must-have tool for developers undertaking serious JSON-RPC 2.0 work.

2. Screenshots

JSON-RPC 2.0 client screenshot
Starting up 		JSON-RPC 2.0 client screenshot
A JSON-RPC session 		JSON-RPC 2.0 client screenshot
Detecting response exceptions

3. Quick start

Unzip the downloaded package into a suitable folder on your computer. The application JAR file requires Java (1.5+) to run. Start it by passing the URL of the JSON-RPC 2.0 server as an argument:

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

You will then be presented with the command prompt of an interactive shell 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 command making a method call on a stock ticker web service:

JSON-RPC 2.0 > getStockQuote ["AMZN"] "id-001"
"$153.71"

Important: If you omit the request ID (set to "id-001" in the above example) the JSON-RPC 2.0 protocol treats the call as a notification and no response will be returned by the server (including errors). If you leave the ID out the shell will remind you by printing "[Notification]" after the command. To save repeated typing of IDs start the shell with the -a, --auto-id option (see startup options).

JSON-RPC 2.0 > notifyOnChange ["AMZN", "$160.00"]
[Notification]

If something goes wrong the shell will print an error message. Here is the standard JSON-RPC 2.0 error that servers return if you try to call a non-existing method:

JSON-RPC 2.0 > getForexQuote ["EUR"] "id-002"
Response [error]: -32601, Method not found

4. Entering requests and notifications, in detail

JSON-RPC 2.0 request commands have the following format:

method_name [parameters] request_id

JSON-RPC 2.0 notification commands have the same format as requests, but omit the ID:

method_name [parameters]

JSON-RPC allows for any string to serve as a method name. However, to simplify shell commands, a small but reasonable restriction is imposed here - only method names that conform to the syntax of JavaScript variable names, dotted domains included, are accepted. Examples of accepted method names:

makePayment
makeWithdrawal
makeDeposit
_search
_search2
billing.add_account
billing.remove_account

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

Positional parameters example:

["Penny Adams", 175.05, true]

Named parameters example (same values):

{"recipient":"Penny Adams", "amount":175.05, "requestReceipt":true}

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

0	     
100
200   
"id-001"    
"id-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

And 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 greater flexibility, the command parser allows the method name, the parameters and the identifier to be entered in any order. Therefore, the following commands are equivalent:

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

5. Shell startup arguments

Apart from the mandatory server_URL argument, the JSON-RPC 2.0 shell accepts several other optional ones:

java -jar jsonrpc2-shell.jar [{-a,--auto-id} request_ID] [-n,--no-strict] 
                             [{-o,--origin} origin_URL] [-t,--trust-all]
			     [{-p,--pretty} compact | regular | off ] 
			     [-s,--stopwatch] [-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 Specify a request ID to be appended automatically to each outgoing RPC message. Use this option to save repeated typing of request IDs in the RPC shell.
-n,--no-strict Disable checking of the "jsonrpc" version field in RPC responses and checking of the content type header (for matching application/json or text/plain) in HTTP responses. Use this option to allow limited compatibility with older JSON-RPC (1.0) servers.
-o,--origin origin_URL Append an "Origin" HTTP header with the specified value to the outgoing requests. Use if the remote web service requires Cross-Origin Resource Sharing (CORS) support.
-p,--pretty compact|regular|off Apply pretty JSON formatting to JSON-RPC 2.0 response results. The default style is compact. You may also select regular pretty formatting or disable it entirely with off.
-s,--stopwatch Displays the time it took each entered JSON remote procedure call to complete (in micro / milliseconds). Use it to measure execution speed and transport delay / latency.
-t,--trust-all Allow self-signed X.509 certificates presented by the web server.
-v,--verbose Print the JSON payload of each incoming and outgoing RPC message. Additional status information may be displayed too.
-h,--help Display a short help text about the shell usage.

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

java -jar jsonrpc2-shell -a 0 -v http://192.168.0.2/jsonrpc/

6. Useful tips

6.1 Displaying the JSON content of RPC messages

To display the JSON content of each request, notification and response start the client with the -v / --verbose option:

java -jar jsonrpc2-shell -v http://192.168.0.2/jsonrpc/

6.2 Setting a default request ID for the entire session

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

java -jar jsonrpc2-shell -a 123 http://192.168.0.2/jsonrpc/

The above example sets a default ID of 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 HTTP cookies support

The JSON-RPC Shell handles HTTP cookies very much like browsers do, to accommodate JSON-RPC servers that use cookies as an out-of-band mean for establishing user sessions.

6.4 Measure remote procedure call time

The -s, --stopwatch option turns a stopwatch for each outgoing JSON-RPC 2.0 request. It then shows how long it took to receive the response, in micro / milliseconds.

java -jar jsonrpc2-shell -s http://192.168.0.2/jsonrpc/

Note that the recorded time represents the time for the server to process the request as well as the times the RPC messages spent in transit.

JSON-RPC 2.0 > user.get { "userID" : "8912374" }
[Received response in 84 ms]
{
  "name"   : "Alice Wonderland",
  "email"  : "[email protected]",
  "mobile" : "0755 123 500 353" 
}

If the JSON-RPC server appends a xProcTime attribute (non-standard) to responses the shell will also print the reported request processing time:

JSON-RPC 2.0 > ws.getVersion
[Received response in 222 ms, reported processing time 17 us]
1.10 (2011-08-21)

6.5 Secure HTTP over SSL/TLS

The JSON-RPC 2.0 shell can also access HTTPS URLs. HTTPS encrypts traffic to the web service and also provides a mean to verify its identity.

Here is an example invocation of the shell to open a JSON-RPC 2.0 session to a HTTPS URL:

java -jar jsonrpc2-shell.jar https://shakespeare.dzhuvinov.com:8443/ldap-auth/

Note that web servers typically accepts SSL/TLS connections on a different port than the standard 80 for plain HTTP. This may be port number 443 (the well-known port for HTTPS) or some other dedicated port, and that you may need to specify its number explicitly as shown above.

If you open an HTTPS URL and get a security exception that looks like this it could mean that the web server presented a self-signed certificate or a certificate signed by an unknown certificate authority (CA). The default policy of Java is to allow HTTPS connections only if the web server presented a valid certificate signed by one of the "official" root CAs such as Verisign or Thawte.

I/O exception: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target

If you choose to allow HTTPS connection to the web server you have two options:

The "lazy" way

Simply start the shell with the -t, --trust-all option to disable certificate issuer checking.

java -jar jsonrpc2-shell.jar -t https://shakespeare.dzhuvinov.com:8443/ldap-auth/

This option is intended for testing and development purposes where you need a quick switch to test encrypted SSL access.

The "recommended" way

Import the server certificate and/or the certificate of the issuing CA into a custom trust store file and then make its details available to Java.

Java comes with a standard keytool command line utility for creating and editing trust/key stores. Alternatively you may use a friendlier GUI tool such as the KeyStore Explorer from Wayne Grant.

To specify a custom trust store start Java with the following -D options (the command is split into several lines for clarity):

java -Djavax.net.ssl.trustStore=my-trust-store-file.jks \
     -Djavax.net.ssl.trustStorePassword=secret \
     -jar jsonrpc2-shell.jar https://shakespeare.dzhuvinov.com:8443/ldap-auth/

6.6 Command history

The JSON-RPC 2.0 shell has a readline-like interface. One useful feature 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 on your keyboard.

6.7 Other useful shell commands

Some other shell commands that might prove useful:

6.8 Method name autocomplete

To enable autocomplete open file autocompleted-methods.txt and list all your autocompleted JSON-RPC method names there, then rebuild the JAR package with 

ant jar

Once autocomplete is enabled you can press [Tab] at the start of a new request to see the available JSON-RPC method names.

Future versions will include intelligent autocomplete where all entered method names that complete successfully will be automatically added to the autocomplete list.

7. Specification and requirements

8. Download

The JSON-RPC 2.0 Shell is offered under a simple and affordable paid license. The source code is also supplied so the software can be freely modified.

Download now JSON-RPC 2.0 Shell

9. Useful links

  1. The JSON-RPC 2.0 specification and user group can be found at http://groups.google.com/group/json-rpc.
  2. This shell tool uses the JSON-RPC 2.0 Base library (also hosted here). It provides a simple and robust Java implementation of the protocol for the correct creation, serialisation and parsing of JSON-RPC 2.0 messages.

10. Change log