jsonrpcclient over HTTP¶

Send JSON-RPC requests over HTTP.

Installation¶

$ pip install jsonrpcclient requests

Usage¶

Set the server details:

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

Send a request with send():

>>> server.send({'jsonrpc': '2.0', 'method': 'cat', 'id': 1})

Sending a request is easier with request(). It takes the method, followed by the arguments to the method:

>>> server.request('cat', name='Mittens')

When sending a single request, the return value is the payload (the result part of the JSON-RPC response message).

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

Batch requests¶

Send multiple requests in one 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.

Note

The server may not support batch requests.

Headers¶

To customize the HTTP headers, pass a headers argument to HTTPServer:

>>> server = HTTPServer('http://example.com/api', headers={'Content-Type': 'application/json-rpc'})

If no headers are given, the following headers are used:

Content-Type: application/json
Accept: application/json

Authentication¶

To make authenticated requests, pass an auth argument to HTTPServer:

>>> server = HTTPServer('http://example.com/api', auth=('user', 'pass'))

For more authentication options, see the requests module which handles the authentication.

Note

In addition to headers and authentication, other arguments can allow you to set the timeout, cookies, SSL verification and more. For the full list of options see the request method here.

Exceptions¶

In the event of a communications problem, the Requests module raises requests.exceptions.RequestException:

try:
    server.request('go')
except requests.exceptions.RequestException as e:
    print(str(e))

The jsonrpcclient library also raises exceptions, for example if the server responded with an error message. The full list of exceptions are here.

Logging¶

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

import logging
logging.getLogger('jsonrpcclient').setLevel(logging.INFO)

Then add a basic handler:

logging.getLogger('jsonrpcclient').addHandler(logging.StreamHandler())

Or use custom handlers and formats:

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

# Request log
request_handler = logging.StreamHandler()
request_handler.setFormatter(logging.Formatter(fmt=request_format))
logging.getLogger('jsonrpcclient.server.request').addHandler(
    request_handler)

# Response log
response_handler = logging.StreamHandler()
response_handler.setFormatter(logging.Formatter(fmt=response_format))
logging.getLogger('jsonrpcclient.server.response').addHandler(
    response_handler)

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).

Examples¶

HTTP Client using Requests

Back home