Damn simple, framework-agnostic JSON-RPC server
Project description
JSON-RPC Server for Python
This is damn simple, framework-agnostic JSON-RPC v2.0 server for Python.
This package has no dependencies. You can build service API without thinking about any framework nor toolkit, and even without thinking about HTTP itself. This package is an implementation of JSON-RPC protocol only, following rules described on http://www.jsonrpc.org/specification
What is JSON-RPC?
JSON-RPC is a protocor similar to XML-RPC, but simpler and very lightweight. There is no necessary to generate nor parse XML documents by using heavy librariers.
You can build easily remote services and call them using clients implemented in many languages. JSON-RPC services are always exposed using HTTP(S) protocol.
For more information please read JSON-RPC v2.0 specification: http://www.jsonrpc.org/specification
Getting started
Installation
Use setuptools
or pip
:
easy_install damn-simple-jsonrpc-server
or
pip install damn-simple-jsonrpc-server
Calculator service example
Let's make calculator service which supports add
and subtract
operations.
(calculator_service.py)
import jsonrpcserver as rpc
calculator = rpc.Service()
@calculator.method
def add(x, y):
return x+y
@calculator.method('subtract')
def sub(x, y):
return x-y
Well... it's done. But where it is accessible? Nowhere!
You can access it directly by calculator
variable, but this is nonsense.
This is an API for HTTP adapters, but not for humans.
Exposing JSON-RPC service via HTTP
Simplest way to expose calculator
service is to use well-known HTTP framework.
It may be a Django, for example:
(urls.py)
from django.conf.urls import patterns, include, url
from .calculator_service import calculator
def calculator_service_view(request):
return calculator.handle_request_body(request.body)
urlpatterns = patterns('',
url(r'^$', calculator_service_view, name='calculator'),
)
But there is a simpler way! :)
Using existing adaptors
If you need quickly expose your service using Django, just use damn simple JSON-RPC Django adaptor, which contains ready to use adaptor:
(urls.py)
from django.conf.urls import patterns, include, url
from calculator_service import calculator
urlpatterns = patterns('',
url(r'^$', 'jsonrpcdjango.serve', kwargs={'service': calculator},
name='calculator'),
)
That's all. Nothing more, nothing less!
Writing custom adaptors
JSON-RPC Service
class has very simple API based on str/unicode or request-like object.
You may use one of the following methods available in Service
class:
handle_request_body
handle_http_request
The handle_request_body
method expects that input string will be a representation of a JSON-RPC Request object.
The handle_http_request
method expects that request-like object will be passed as an argument.
In that case request-like object must contain body
attribute with string representation
of JSON-RPC request.
Return value of handle_request_body
and handle_http_request
is always a str/unicode
with a JSON-RPC Response object representation (success and error responses are returned
same way, as described in http://www.jsonrpc.org/specification, but will contain result
and error
keys respectively).
Authentication, CSRF, other stuff...
Authentication and CSRF are HTTP-related topics. You may implement them in adaptors or just use tools from your favourite HTTP framework. For Django framework you may simply decorate whole service:
(urls.py)
import jsonrpcdjango as rpc
[...]
urlpatterns = patterns('',
url(r'^$', login_required(rpc.serve), kwargs={'service': calculator},
name='calculator'),
To enable or disable CSRF just use specific adaptor:
jsonrpcdjango.serve
for CSRF-less handlerjsonrpcdjango.csrf_serve
for CSRF-protected handler- or use disrectly Django's decorators
csrf_exempt
,csrf_protect
or enableCsrfViewMiddleware
(read https://docs.djangoproject.com/en/dev/ref/csrf/ for details)
Currently there is no possibility to decorate specific methods of the service with jsonrpcdjango
adaptor.
Authorization
If you want add authorization to your method you should use similar solution as for authentication. For Django framework you may simply decorate whole service:
(urls.py)
import jsonrpcdjango as rpc
[...]
urlpatterns = patterns('',
url(r'^$', permission_required('can_use_rpc')(rpc.serve), kwargs={'service': calculator},
name='calculator'),
Currently there is no possibility to decorate specific methods of the service with jsonrpcdjango
adaptor.
Accessing original HTTP request inside service methods
Sometimes you may need access to specific request data added somewhere
in middleware stack. In that case you can register JSON-RPC method with
additional argument takes_http_request=True
. Original request
object
will be passed as first argument.
If you're using Django as an HTTP framework and jsonrpcdjango
adaptor,
you can provide access to Django's HttpRequest
object inside service method
without any hacks. Just declare takes_http_request=True
at registering
time. This will make your service dependend on Django, but will add more flexibility.
(calculator_service.py)
calculator = rpc.Service()
[...]
@calculator.method(takes_http_request=True)
def beast_add(request, x, y):
if request.user.is_superuser:
return x+y
else:
return 666
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for damn-simple-jsonrpc-server-0.4.4.post1.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 7575674a3b59750d1ff154055cc390cc47db55d2970736da5b7083463b24d10f |
|
MD5 | 701a769cea029178be252d1d1e813e58 |
|
BLAKE2b-256 | e4e1dd2309b8f5a574bb7c9412fc35d800cf8afc12c87838f0549891f4ccf899 |
Hashes for damn_simple_jsonrpc_server-0.4.4.post1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | afb63b394e21b2f1db65c89284fbe3155dcc8659ea3be40b841079764577da21 |
|
MD5 | 5972c4d1ea2aee0582d7e46c6d697e91 |
|
BLAKE2b-256 | df6d4cec1a542beda39fde29e5b8b0ffdbd3a8b83f38a38f46987f33034e398f |