{"id":13696907,"url":"https://github.com/samuraisam/django-json-rpc","last_synced_at":"2025-10-30T04:01:53.108Z","repository":{"id":57420553,"uuid":"242732","full_name":"samuraisam/django-json-rpc","owner":"samuraisam","description":"JSON-RPC Implementation for Django","archived":false,"fork":false,"pushed_at":"2019-02-20T06:37:03.000Z","size":233,"stargazers_count":286,"open_issues_count":21,"forks_count":83,"subscribers_count":22,"default_branch":"master","last_synced_at":"2024-10-13T17:37:57.412Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/samuraisam.png","metadata":{"files":{"readme":"README.mdown","changelog":null,"contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2009-07-03T20:08:07.000Z","updated_at":"2024-07-03T07:35:33.000Z","dependencies_parsed_at":"2022-09-16T09:23:04.339Z","dependency_job_id":null,"html_url":"https://github.com/samuraisam/django-json-rpc","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samuraisam%2Fdjango-json-rpc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samuraisam%2Fdjango-json-rpc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samuraisam%2Fdjango-json-rpc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samuraisam%2Fdjango-json-rpc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/samuraisam","download_url":"https://codeload.github.com/samuraisam/django-json-rpc/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224369816,"owners_count":17299961,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-02T18:00:49.736Z","updated_at":"2025-10-30T04:01:48.070Z","avatar_url":"https://github.com/samuraisam.png","language":"Python","funding_links":[],"categories":["Framework Integrations"],"sub_categories":[],"readme":"Django JSON-RPC\n===============\n\n![Travis Build Status](https://travis-ci.org/samuraisam/django-json-rpc.svg?branch=master) [![PyPI version](https://badge.fury.io/py/django-json-rpc.svg)](http://badge.fury.io/py/django-json-rpc)\n\nA basic JSON-RPC Implementation for your Django-powered sites.\n\nFeatures:\n\n* Simple, pythonic API\u003c/li\u003e\n* Support for Django authentication\u003c/li\u003e\n* Support for all official [Django Python/Version](https://docs.djangoproject.com/en/1.8/faq/install/#what-python-version-can-i-use-with-django) combinations\u003c/li\u003e\n* Supports JSON-RPC 1.0, 1.1, 1.2 and 2.0 Spec\n* Proxy to test your JSON Service\n* Run-time type checking\n* Graphical JSON-RPC browser and web console\n* Provides `system.describe`\n\n\nThe basic API:\n\n**myproj/myapp/views.py**\n\n    from jsonrpc import jsonrpc_method\n\n    @jsonrpc_method('myapp.sayHello')\n    def whats_the_time(request, name='Lester'):\n      return \"Hello %s\" % name\n\n    @jsonrpc_method('myapp.gimmeThat', authenticated=True)\n    def something_special(request, secret_data):\n      return {'sauce': ['authenticated', 'sauce']}\n\n\n**myproj/urls.py**\n\n    from django.conf.urls.defaults import *\n    from jsonrpc import jsonrpc_site\n    import myproj.myapp.views # you must import the views that need connected\n\n    urlpatterns = patterns('',\n      url(r'^json/browse/', 'jsonrpc.views.browse', name=\"jsonrpc_browser\"), # for the graphical browser/web console only, omissible\n      url(r'^json/', jsonrpc_site.dispatch, name=\"jsonrpc_mountpoint\"),\n      (r'^json/(?P\u003cmethod\u003e[a-zA-Z0-9.]+)$', jsonrpc_site.dispatch) # for HTTP GET only, also omissible\n    )\n\n\n**To test your service:**\nYou can test your service using the provided graphical browser and console,\navailable at http://YOUR_URL/json/browse/ (if using the url patterns from above) or with the included ServiceProxy:\n\n    \u003e\u003e\u003e from jsonrpc.proxy import ServiceProxy\n\n    \u003e\u003e\u003e s = ServiceProxy('http://localhost:8080/json/')\n\n    \u003e\u003e\u003e s.myapp.sayHello('Sam')\n    {u'error': None, u'id': u'jsonrpc', u'result': u'Hello Sam'}\n\n    \u003e\u003e\u003e s.myapp.gimmeThat('username', 'password', 'test data')\n    {u'error': None, u'id': u'jsonrpc', u'result': {u'sauce': [u'authenticated', u'sauce']}}\n\nWe add the `jsonrpc_version` variable to the request object. It be either '1.0', '1.1' or '2.0'. Arg.\n\nGuide\n=====\n\n### Adding JSON-RPC to your application\n\n#### 1. Install django-json-rpc\n\n    git clone git://github.com/samuraisam/django-json-rpc.git\n    cd django-json-rpc\n    python setup.py install\n\n    # Add 'jsonrpc' to your INSTALLED_APPS in your settings.py file\n\n#### 2. Write JSON-RPC methods\n\n    from jsonrpc import jsonrpc_method\n\n    @jsonrpc_method('app.register')\n    def register_user(request, username, password):\n      u = User.objects.create_user(username, 'internal@app.net', password)\n      u.save()\n      return u.__dict__\n\n    @jsonrpc_method('app.change_password', authenticated=True)\n    def change_password(request, new_password):\n      request.user.set_password(new_password)\n      request.user.save()\n      return u.__dict__\n\n#### 3. Add the JSON-RPC mountpoint and import your views\n\n    from jsonrpc import jsonrpc_site\n    import app.views\n\n    urlpatterns = patterns('',\n      url(r'^json/$', jsonrpc_site.dispatch, name='jsonrpc_mountpoint'),\n      # ... among your other URLs\n    )\n\n\n### The jsonrpc_method decorator\nWraps 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.\n\n`jsonrpc.jsonrpc_method(name, authenticated=False, safe=False, validate=False)`\n\u003cul\u003e\n\u003cli\u003e\n`name`\n\nThe name of your method. IE: `namespace.methodName`\n\u003c/li\u003e\n\u003cli\u003e\n`authenticated=False`\n\nAdds `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`.\n\nYou 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`.\n\u003c/li\u003e\n\u003cli\u003e\n`safe=False`\n\nDesignates whether or not your method may be accessed by HTTP GET. By default this is turned off.\n\u003c/li\u003e\n\u003cli\u003e\n`validate=False`\n\nValidates 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:\n\n      @jsonrpc_method('myapp.specialSauce(Array, String)', validate=True)\n      def special_sauce(self, ingredients, instructions):\n        return SpecialSauce(ingredients, instructions)\n\nCalls 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.\n\n*NOTE:* Type checking is only available on Python versions 2.6 or greater.\n\u003c/li\u003e\n\u003cli\u003e\n`site=default_site`\n\nDefines which site the jsonrpc method will be added to. Can be any\nobject that provides a `register(name, func)` method.\n\u003c/li\u003e\n\u003c/ul\u003e\n\n### Using type checking on methods (Python 2.6 or greater)\nWhen 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.\n\n      @jsonrpc_method('app.addStrings(arg1=String, arg2=String) -\u003e String', validate=True)\n      def add_strings(request, arg1, arg2):\n        return arg1 + arg2\n\nHowever 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.\n\n**Note:** Return type information is used only for reference, return value types are not checked.\n\nTypes can be specified a number of ways, the following are all equivalent:\n\n      # using JSON types:\n      @jsonrpc_method('app.findSelection(query=Object, limit=Number)')\n\n      # using Python types:\n      @jsonrpc_method('app.findSelection(query=dict, limit=int)')\n\n      # with mixed keyword parameters\n      @jsonrpc_method('app.findSelection(dict, limit=int)')\n\n      # with no keyword parameters\n      @jsonrpc_method('app.findSelection(dict, int)')\n\n      # with a return value\n      @jsonrpc_method('app.findSelection(dict, int) -\u003e list')\n\n### Using the browser\nTo access the browser simply add another entry to your `urls.py` file, before the json dispatch one. Make sure to include the name attribute of each url.\n\n    urlpatterns = patterns('',\n      ...\n      url(r'^json/browse/$', 'jsonrpc.views.browse', name='jsonrpc_browser')\n      url(r'^json/', jsonrpc_site.dispatch, name=\"jsonrpc_mountpoint\"),\n      ...\n    )\n\n\n### Enabling HTTP-GET\nJSON-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.\n\n    urlpatterns += patterns('',\n      (r'^json/(?P\u003cmethod\u003e[a-zA-Z0-9.-_]+)$', jsonrpc_site.dispatch),\n    )\n\nEach method that you want to be accessible by HTTP GET must also be marked safe in the method decorator:\n\n    @jsonrpc_method('app.trimTails(String)', safe=True)\n    def trim_tails(request, arg1):\n      return arg1[:5]\n\nYou can then call the method by loading `/jsonrpc/app.trimTails?arg1=omgnowai`\n\n### Using authentication on methods\nThere 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.\n\n    @jsonrpc_method('app.thupertheecrit', authenticated=True)\n    def thupertheecrit(request, value):\n      p = request.user.get_profile()\n      p.theecrit = value\n      p.save()\n      return p.__dict__\n\nUsing your own authentication method:\n\n    def mah_authenticate(username, password):\n      return CustomUserClass.authenticate(username, password)\n\n    @jsonrpc_method('app.thupertheecrit', authenticated=mah_authenticate)\n    def thupertheecrit(request, value):\n      request.user.theecrit = value\n      request.user.save()\n      return request.user.__dict__\n\nIn 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.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamuraisam%2Fdjango-json-rpc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsamuraisam%2Fdjango-json-rpc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamuraisam%2Fdjango-json-rpc/lists"}