Welcome, guest | Sign In | My Account | Store | Cart

Notice! PyPM is being replaced with the ActiveState Platform, which enhances PyPM’s build and deploy capabilities. Create your free Platform account to download ActivePython or customize Python with the packages you require and get automatic updates.

pypm install django-json-rpc

How to install django-json-rpc

  1. Download and install ActivePython
  2. Open Command Prompt
  3. Type pypm install django-json-rpc
 Python 2.7Python 3.2Python 3.3
Windows (32-bit)
0.6.1 Available View build log
Windows (64-bit)
0.6.1 Available View build log
Mac OS X (10.5+)
0.6.1 Available View build log
Linux (32-bit)
0.6.1 Available View build log
Linux (64-bit)
0.6.1 Available View build log
Depended by
Lastest release
version 0.6.1 on Jan 5th, 2011

Features: * Simple, pythonic API * Support for Django authentication * Supports JSON-RPC 1.0, 1.1, 1.2 and 2.0 Spec * Proxy to test your JSON Service * Run-time type checking * Graphical JSON-RPC browser and web console * Provides system.describe

The basic API

## myproj/myapp/views.py

from jsonrpc import jsonrpc_method

@jsonrpc_method('myapp.sayHello') def whats_the_time(request, name='Lester'): return "Hello %s" % name

@jsonrpc_method('myapp.gimmeThat', authenticated=True) def something_special(request, secret_data): return {'sauce': ['authenticated', 'sauce']}

## myproj/urls.py

from django.conf.urls.defaults import * from jsonrpc import jsonrpc_site import myproj.myapp.views # you must import the views that need connected

urlpatterns += patterns('', url(r'^json/', jsonrpc_site.dispatch, name="jsonrpc_mountpoint"), url(r'^json/browse/', 'jsonrpc.views.browse', name="jsonrpc_browse"), # for the graphical browser/web console only, omissible (r'^json/(?P<method>[a-zA-Z0-9.]+)$', jsonrpc_site.dispatch) # for HTTP GET only, also omissible )

To test your service

You can test your service using the provided graphical browser and console, available at http://YOUR_URL/json/browse/ (if using the url patterns from above) or with the included ServiceProxy:

>>> from jsonrpc.proxy import ServiceProxy
>>> s = ServiceProxy('http://localhost:8080/json/')
>>> s.myapp.sayHello('Sam')
{u'error': None, u'id': u'jsonrpc', u'result': u'Hello Sam'}
>>> s.myapp.gimmeThat('username', 'password', 'test data')
{u'error': None, u'id': u'jsonrpc', u'result': {u'sauce': [u'authenticated', u'sauce']}}

Method Browser:


We add the jsonrpc_version variable to the request object. It be either '1.0', '1.1' or '2.0'. Arg.


Adding JSON-RPC to your application

1. Install django-json-rpc

System Message: WARNING/2 (<string>, line 74)

Literal block expected; none found.

git clone git://github.com/samuraisam/django-json-rpc.git cd django-json-rpc python setup.py install

# Add 'jsonrpc' to your INSTALLED_APPS in your settings.py file

2. Write JSON-RPC methods

System Message: WARNING/2 (<string>, line 84)

Literal block expected; none found.

from jsonrpc import jsonrpc_method

@jsonrpc_method('app.register') def register_user(request, username, password): u = User.objects.create_user(username, 'internal@app.net', password) u.save() return u.__dict__

@jsonrpc_method('app.change_password', authenticated=True) def change_password(request, new_password): request.user.set_password(new_password) request.user.save() return u.__dict__

3. Add the JSON-RPC mountpoint and import your views

System Message: WARNING/2 (<string>, line 102)

Literal block expected; none found.

from jsonrpc import jsonrpc_site import app.views

urlpatterns = patterns('', url(r'^json/$', jsonrpc_site.dispatch, name='jsonrpc_mountpoint'), # ... among your other URLs )

The jsonrpc_method decorator

Wraps a function turns it into a json-rpc method. Adds several attributes to the function speific to the JSON-RPC machinery and adds it to the default jsonrpc_site if one isn't provided. You must import the module containing these functions in your urls.py.

jsonrpc.jsonrpc_method(name, authenticated=False, safe=False, validate=False)


System Message: WARNING/2 (<string>, line 122)

Literal block expected; none found.


The name of your method. IE: namespace.methodName The method name can include type information, like ns.method(String, Array) -> Nil.


Adds username and password arguments to the beginning of your method if the user hasn't already been authenticated. These will be used to authenticate the user against django.contrib.authenticate If you use HTTP auth or other authentication middleware, username and password will not be added, and this method will only check against request.user.is_authenticated.

You may pass a callablle to replace django.contrib.auth.authenticate as the authentication method. It must return either a User or None and take the keyword arguments username and password.


Designates whether or not your method may be accessed by HTTP GET. By default this is turned off.


Validates the arguments passed to your method based on type information provided in the signature. Supply type information by including types in your method declaration. Like so:

@jsonrpc_method('myapp.specialSauce(Array, String)', validate=True) def special_sauce(self, ingredients, instructions): return SpecialSauce(ingredients, instructions)

Calls to myapp.specialSauce will now check each arguments type before calling special_sauce, throwing an InvalidParamsError when it encounters a discrepancy. This can significantly reduce the amount of code required to write JSON-RPC services.


Defines which site the jsonrpc method will be added to. Can be any object that provides a register(name, func) method.

Using type checking on methods (Python 2.6 or greater)

When writing web services you often end up manually checking the types of parameters passed. django-json-rpc provides a way to eliminate much of that code by specifying the types in your method signature. As specified in the JSON-RPC spec the available types are Object Array Number Boolean String Nil and Any meaning any type:

@jsonrpc_method('app.addStrings(arg1=String, arg2=String) -> String', validate=True)

System Message: ERROR/3 (<string>, line 176)

Inconsistent literal block quoting.

def add_strings(request, arg1, arg2): return arg1 + arg2

However contrived this example, a lot of extra information about our function is available. The system.describe method will automatically be able to provide more information about the parameters and return type. Provide validate=True to the jsonrpc_method decorator and you can be guaranteed to receive two string objects when add_strings is called.

Note: Return type information is used only for reference, return value types are not checked.

Types can be specified a number of ways, the following are all equivalent:

# using JSON types:

System Message: ERROR/3 (<string>, line 191)

Inconsistent literal block quoting.

@jsonrpc_method('app.findSelection(query=Object, limit=Number)')

# using Python types: @jsonrpc_method('app.findSelection(query=dict, limit=int)')

# with mixed keyword parameters @jsonrpc_method('app.findSelection(dict, limit=int)')

# with no keyword parameters @jsonrpc_method('app.findSelection(dict, int)')

# with a return value @jsonrpc_method('app.findSelection(dict, int) -> list')

Using the browser

To access the browser simply add another entry to your urls.py file. Make sure to include the name attribute of each url:

System Message: WARNING/2 (<string>, line 211)

Literal block expected; none found.

urlpatterns += patterns('', url(r'^json/browse/$', 'jsonrpc.views.browse', name='jsonrpc_browser') )

Enabling HTTP-GET

JSON-RPC 1.1 includes support for methods which are accessible by HTTP GET which it calls idempotent. Add the following to your urls.py file to set up the GET URL:

System Message: WARNING/2 (<string>, line 223)

Literal block expected; none found.

urlpatterns += patterns('', (r'^json/(?P<method>[a-zA-Z0-9.-_]+)$', jsonrpc_site.dispatch), )

Each method that you want to be accessible by HTTP GET must also be marked safe in the method decorator:

@jsonrpc_method('app.trimTails(String)', safe=True)

System Message: ERROR/3 (<string>, line 231)

Inconsistent literal block quoting.

def trim_tails(request, arg1): return arg1[:5]

You can then call the method by loading /jsonrpc/app.trimTails?arg1=omgnowai

Using authentication on methods

There is no specific support for authentication in the JSON-RPC spec beyond whatever authentication the transport offers. To restrict access to methods to registered users provide authenticated=True to the method decorator. Doing so will add two arguments to the beginning of your method signature, username and password (and always in that order). By default, the credentials are authenticated against the builtin User database but any method can be used:

@jsonrpc_method('app.thupertheecrit', authenticated=True)

System Message: ERROR/3 (<string>, line 247)

Inconsistent literal block quoting.

def thupertheecrit(request, value): p = request.user.get_profile() p.theecrit = value p.save() return p.__dict__

Using your own authentication method:

System Message: WARNING/2 (<string>, line 255)

Literal block expected; none found.

def mah_authenticate(username, password): return CustomUserClass.authenticate(username, password)

@jsonrpc_method('app.thupertheecrit', authenticated=mah_authenticate) def thupertheecrit(request, value): request.user.theecrit = value request.user.save() return request.user.__dict__

In case authentication is handled before your method is called, like in some middleware, providing authenticated=True to the method decorator will only check that request.user is authenticated and won't add any parameters to the beginning of your method.

Subscribe to package updates

Last updated Jan 5th, 2011

Download Stats

Last month:4

What does the lock icon mean?

Builds marked with a lock icon are only available via PyPM to users with a current ActivePython Business Edition subscription.

Need custom builds or support?

ActivePython Enterprise Edition guarantees priority access to technical support, indemnification, expert consulting and quality-assured language builds.

Plan on re-distributing ActivePython?

Get re-distribution rights and eliminate legal risks with ActivePython OEM Edition.