jsonrpcake 1.1.0

JSONRPCake - a CLI JSON-RPC client for humans.

JSONRPCake is a command line JSON-RPC client that wraps the jsonrpc-ns library. It is a fork of HTTPie written by Jakub Roztocil. Its goal is to make CLI interaction with JSON-RPC 2.0 services as human-friendly as possible. It provides a simple jsonrpc command that allows for sending arbitrary JSON-RPC requests using a simple and natural syntax, and displays colorized responses. JSONRPCake can be used for testing, debugging, and generally interacting with JSON-RPC servers.

JSONRPCake is written in Python, and under the hood it uses the jsonrpc-ns and Pygments libraries.

Table of Contents

• Main Features

• Installation

• Usage

• JSON-RPC Address and Port

• JSON-RPC Method

• Parameters

• Redirected Input

• Terminal Output

• Redirected Output

• Authors

• Licence

Main Features

• Expressive and intuitive syntax

• Formatted and colorized terminal output

• Built-in JSON support

• Arbitrary request data

Installation

The latest stable version of JSONRPCake can always be installed or updated to via pip:

$ pip install --upgrade jsonrpcake

Usage

Hello World:

$ jsonrpc example.org:3000 hello

Synopsis:

$ jsonrpc ADDRESS:PORT METHOD [PARAMETER [PARAMETER [...]]]

See also jsonrpc --help.

Examples

JSON params:

$ jsonrpc example.org:3000 update name=John uid:=1234

JSON-RPC Address and Port

The address and port are separated by a ‘:’. The TCP port is required. When the address omitted, the default address is localhost.

$ jsonrpc :3000 users

Is equivalent to:

$ jsonrpc localhost:3000 users

JSON-RPC Method

The name of the JSON-RPC method comes right after the address and port:

$ jsonrpc example.org:3000 users

The METHOD argument is required.

Parameters

JSON parameters are key/value pairs specified after the `METHOD`. The parameter type is distinguished only by the separator used: :, =, :=, ==, @, =@, and :=@. The ones with an @ expect a file path as value.

Item Type	Description
Data Fields field=value,	Request data fields to be serialized as a JSON object (default).
Raw JSON fields field:=json, field:=@file.json	Useful when sending JSON and one or more fields need to be a Boolean, Number, nested Object, or an Array, e.g., meals:='["ham","spam"]' or pies:=[1,2,3] (note the quotes).

Redirected Input

A universal method for passing request parameters is through redirected stdin (standard input). Such data is buffered and then with no further processing used as the request body. There are multiple useful ways to use piping:

Redirect from a file:

$ jsonrpc example.com:7080 add.user < person.json

You can use echo for simple data:

$ echo '{"uid": 1234, "name": "John"}' | jsonrpc example.com:3000 update.userinfo

You can use cat to enter multiline data on the terminal:

$ cat | jsonrpc example.com:3000 update
<paste>
^D

To prevent JSONRPCake from reading stdin data you can use the --ignore-stdin option.

Terminal Output

JSONRPCake does several things by default in order to make its terminal output easy to read.

Colors and Formatting

Syntax highlighting is applied to the response (where it makes sense). You can choose your prefered color scheme via the --style option if you don’t like the default one (see $ jsonrpc --help for the possible values).

Also, the following formatting is applied:

• JSON data is indented, sorted by keys, and unicode escapes are converted to the characters they represent.

One of these options can be used to control output processing:

--pretty=all	Apply both colors and formatting. Default for terminal output.
--pretty=colors	Apply colors.
--pretty=format	Apply formatting.
--pretty=none	Disables output processing. Default for redirected output.

Redirected Output

JSONRPCake uses different defaults for redirected output than for terminal output:

• Formatting and colors aren’t applied (unless --pretty is specified).

• Only the response message is printed.

Force colorizing and formatting, and show both the request and the response in less pager:

$ jsonrpc --pretty=all --verbose example.org:7080 info | less -R

The -R flag tells less to interpret color escape sequences included JSONRPCake`s output.

Authors

Forked by Joe Hillenbrand

Jakub Roztocil created HTTPie and these fine people have contributed.

Licence

Please see LICENSE.

---