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:
>>> 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
'meow'
If you’re not interested in a response, use notify
instead of request
.
Lower-Level¶
Send your own message with send
:
>>> server.send({'jsonrpc': '2.0', 'method': 'ping'})
A Request
class is provided to simplify making a JSON-RPC
message:
>>> from jsonrpcclient.request import Request
>>> Request('cat', name='Mittens')
{"jsonrpc": "2.0", "method": "cat", "params": {"name": "Mittens"}, "id": 1}
Send a Request
:
>>> server.send(Request('cat', name='Mittens'))
--> {"jsonrpc": "2.0", "method": "cat", "params": {"name": "Mittens"}, "id": 2}
<-- {"jsonrpc": "2.0", "result": "meow", "id": 2}
'meow'
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.
Configuration¶
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.
Exceptions¶
The Requests module raises a requests.exceptions.RequestException if there’s a problem transferring the message. Other exceptions raised are:
jsonrpcclient.ParseError: | |
---|---|
Raised if the response is not valid JSON. | |
jsonschema.ValidationError: | |
Raised if the response is valid JSON but not a valid JSON-RPC response. | |
jsonrpcclient.ReceivedErrorResponse: | |
Raised if the server responded with a valid JSON-RPC error object. |
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). |