90 lines
2.1 KiB
ReStructuredText
90 lines
2.1 KiB
ReStructuredText
|
Overview
|
||
|
|
========
|
||
|
|
|
||
|
|
This section provides the general overview of the library.
|
||
|
|
|
||
|
|
Installation
|
||
|
|
------------
|
||
|
|
|
||
|
|
.. code-block:: shell
|
||
|
|
|
||
|
|
$ pip install bthlabs_jsonrpc_core
|
||
|
|
|
||
|
|
Usage
|
||
|
|
-----
|
||
|
|
|
||
|
|
While this package is built to mostly support other integrations, it's possible
|
||
|
|
to use it directly to add a JSONRPC endpoint to an existing Web app.
|
||
|
|
|
||
|
|
Consider the following Flask app:
|
||
|
|
|
||
|
|
.. code-block:: python
|
||
|
|
|
||
|
|
from bthlabs_jsonrpc_core import Executor, register_method
|
||
|
|
from flask import Flask, jsonify, request
|
||
|
|
|
||
|
|
app = Flask(__name__)
|
||
|
|
|
||
|
|
|
||
|
|
@register_method('hello')
|
||
|
|
def hello(who='World'):
|
||
|
|
return f'Hello, {who}!'
|
||
|
|
|
||
|
|
|
||
|
|
@app.route('/rpc', methods=['POST'])
|
||
|
|
def post_rpc():
|
||
|
|
executor = Executor()
|
||
|
|
serializer = executor.execute(request.get_data())
|
||
|
|
|
||
|
|
return jsonify(serializer.data)
|
||
|
|
|
||
|
|
This application will allow calling the ``hello`` JSONPRC method via the
|
||
|
|
``POST /rpc`` endpoint. This approach is limited, as it doesn't provide the
|
||
|
|
means of performing any access control and other checks, leaving the app to
|
||
|
|
do this. In practice, it's best to rely on framework integrations.
|
||
|
|
|
||
|
|
Calling Conventions
|
||
|
|
-------------------
|
||
|
|
|
||
|
|
The JSONRPC 2.0 spec calls for two conventions for passing method parameters -
|
||
|
|
*by-position* (using an array) or *by-name* (using a JSON object). BTHLabs
|
||
|
|
JSONRPC implements both.
|
||
|
|
|
||
|
|
The ``hello`` method from the Flask app example could be called using the
|
||
|
|
following payloads.
|
||
|
|
|
||
|
|
.. code-block:: json
|
||
|
|
|
||
|
|
{
|
||
|
|
"jsonrpc": "2.0",
|
||
|
|
"id": "hello"
|
||
|
|
}
|
||
|
|
|
||
|
|
This payload would call the method without arguments. In this case, it would
|
||
|
|
return ``Hello, World!``.
|
||
|
|
|
||
|
|
.. code-block:: json
|
||
|
|
|
||
|
|
{
|
||
|
|
"jsonrpc": "2.0",
|
||
|
|
"id": "hello",
|
||
|
|
"params": ["JSONRPC"]
|
||
|
|
}
|
||
|
|
|
||
|
|
This payload would call the method with one positional argument. In this case,
|
||
|
|
it would return ``Hello, JSONRPC!``.
|
||
|
|
|
||
|
|
.. code-block:: json
|
||
|
|
|
||
|
|
{
|
||
|
|
"jsonrpc": "2.0",
|
||
|
|
"id": "hello",
|
||
|
|
"params": {"who": "JSONRPC"}
|
||
|
|
}
|
||
|
|
|
||
|
|
This payload would call the method with one keyword argument. In this case,
|
||
|
|
it would return ``Hello, JSONRPC!``.
|
||
|
|
|
||
|
|
While writing your methods, you should consider these conventions and specify
|
||
|
|
your method signatures accordingly.
|