jsonrpcclient over HTTP

Send JSON-RPC requests over HTTP.


$ pip install jsonrpcclient requests


Set the server details:

>>> from jsonrpcclient.http_server import HTTPServer
>>> server = HTTPServer('http://pets.com/api')

Send a request:

>>> response = server.request('cat', name='Mittens')
--> {"jsonrpc": "2.0", "method": "cat", "params": {"name": "Mittens"}, "id": 1}
<-- {"jsonrpc": "2.0", "result": "meow", "id": 1}

The first argument is the JSON-RPC method, followed by arguments to the method.

The return value is the payload, (the result part of the response message):

>>> response

If you’re not interested in a response, use notify() instead of request().


Send your own message with send():

>>> server.send({'jsonrpc': '2.0', 'method': 'cat', 'params': {'name': 'Mittens'}, 'id': 5})

A Request class is provided to simplify making a JSON-RPC message:

>>> Request('cat', name='Mittens', request_id=5)
{"jsonrpc": "2.0", "method": "cat", "params": {"name": "Mittens"}, "id": 5}

Send a Request:

>>> server.send(Request('cat', name='Mittens', request_id=5))
--> {"jsonrpc": "2.0", "method": "cat", "params": {"name": "Mittens"}, "id": 5}
<-- {"jsonrpc": "2.0", "result": "meow", "id": 5}

There’s also a Notification class if you don’t need a response.

Batch requests

With batch requests you can send multiple requests in a single message:

>>> server.send([{'jsonrpc': '2.0', 'method': 'cat'}, {'jsonrpc': '2.0', 'method': 'dog'}])

Send multiple Request objects:

>>> server.send([Request('cat'), Request('dog')])

Using list comprehension to get the cube of ten numbers:

>>> server.send([Request('cube', i) for i in range(10)])

Unlike single requests, batch requests return the whole JSON-RPC response object, i.e. a list of responses for each request that had an id member.

The server may not support batch requests.


The Requests module’s Session is available so you can configure that before sending any requests.

For example, for SSL authentication:

>>> server.session.verify = '/path/to/cert'

Basic Auth:

>>> server.session.auth = ('user', 'pass')

Custom HTTP headers:

>>> server.session.headers.update({'Content-Type': 'application/json-rpc'})

You can also configure the Request options when calling send:

>>> server.send(req, auth=('user', 'pass'))
>>> server.send(req, headers={'Content-Type': 'application/json-rpc'})

As in the requests library, any dictionaries passed to send in named arguments will be merged with the session-level values that are set. The method-level parameters override session parameters.


The Requests module raises a requests.exceptions.RequestException if there’s a problem transferring the message. Other exceptions raised are:

 Raised if the response is not valid JSON.
 Raised if the response is valid JSON but not a valid JSON-RPC response.
 Raised if the server responded with an error message.


To see the JSON-RPC messages going back and forth, set the logging level to INFO:

import logging

Then add a basic handler:


Or use custom handlers and formats:

request_format = '%(endpoint)s --> %(message)s'
response_format = '%(endpoint)s <-- %(message)s'

# Request log
request_handler = logging.StreamHandler()

# Response log
response_handler = logging.StreamHandler()

The request format has these fields:

endpoint:The server endpoint, eg. http://example.com/api.
http_headers:The full HTTP headers.
message:The JSON request (the body).

The response format has these fields:

endpoint:The server endpoint, eg. http://example.com/api.
http_code:The HTTP status code received from the server, eg. 400.
http_reason:The description of the status code, eg. BAD REQUEST.
http_headers:The full HTTP headers.
message:The JSON response (the body).