Clone wiki

django-roa / GettingStarted

Getting started with Django-ROA

Basic use

In order to use remote access with your models, there are 3 steps:

  • inherit from django_roa.Model for your models.
  • inherit from django_roa.Manager for your own managers if you'd like to extend/modify the default one.
  • inherit from django_roa.ModelAdmin for your own admin if you'd like to set custom options.
  • define get_resource_url_list static method in your models to access your remote resource in a RESTful way. Optionally, use get_resource_url_detail method for your model in order to define your own detail url, default is <resource_url_list><resource_url_detail>/

You can take a look at what have been done in examples' projects for a complete example.

How does it works

Each time a request is passed to the database, an HTTP request is done to the remote server with the right method (GET, POST, PUT or DELETE) given the get_resource_url_* methods specified in the model's definition.

A little example

Here is a fully functional example (abstract from example project, see tests too):

from django_roa import Model

class RemotePage(Model):
    title = models.CharField(max_length=50, blank=True, null=True)
    def get_resource_url_list():
        return u'http://your-url/'

And then you'll be able to do whatever you want with this (remote) resource:

>>> from django_roa_client.models import RemotePage
>>> page = RemotePage.objects.create(title=u'A first remote page')
>>> page
<RemotePage: A first remote page (1)>
>>> page.title = u'Another title'
>>> page = RemotePage.objects.get(title=u'Another title')
>>> page.title
u'Another title'
>>> pages = RemotePage.objects.all()
>>> pages
[<RemotePage: Another title (1)>]
>>> page.delete()
>>> RemotePage.objects.all()
>>> RemotePage.objects.count()

Installation notes

Python 2.4+ and Django 1.2 alpha. Py-restclient 1.3.2 is included, it will use pycurl, urllib2 or httplib2. Django-piston 0.2.1 is included too. Those dependencies will be removed from the distribution of the project once it's stabilized.

You just need to add the django_roa application into your settings:

  • add django_roa to your INSTALLED_APPS setting:
  • add ROA_MODELS = True in your settings.
  • specify the mapping of applications' names in your ROA_MODEL_NAME_MAPPING setting:
    ('django_roa_client.', 'django_roa_server.'),

Optionally, you can use a remote auth if your users are stored on the remote repository:

  • add django_roa.remoteauth to your INSTALLED_APPS setting:
  • add RemoteUserModelBackend to your AUTHENTICATION_BACKENDS setting:
  • in this case ROA_MODEL_NAME_MAPPING setting will look like this:
    # local name: remote name
    ('django_roa_client.', 'django_roa_server.'),
    ('remoteauth.', 'auth.'),

Note that ROA_URL_OVERRIDES_* settings allow you to customize the URLs requested by this application. See specifications for a more detailed explanation.

Running tests

The best thing to verify that your installation is complete is to launch Django-ROA's tests.

First, you need to create the remote database, go to examples/django_roa_server and run syncdb command with --noinput option in order to create a superuser named roa_user from fixtures:

    $ python syncdb --noinput

Now you can launch the project's server on port 8081 in order to test the suite with this command:

    $ python runserver 8081

Then go to examples/django_roa_client and run this command (while the server is running, of course):

    $ python test django_roa_client

It should return no error and you will be able to see logs from the test server which confirm that it works as expected: remote requests are done.

Note: do not try to launch tests' projects if you put django_roa application folder into your own project folder, otherwise it will fail. Django do not handle very well projects inside projects.

Running test applications

Django RAO comes with a set of examples applications, wich demonstrate how it's works, by the practice.

Here are some steps to launch this examples application.


All example applications remains in the "example" app, so, go throught, synchronize the database and launch the django development server (the server side of django-roa), listening on port 8081.

cd examples/django_roa_server
python syncdb
python runserver 8081


Now, launch the client part:

cd examples/django_roa_client
python syncdb
python runserver

That's all ! Go to http://localhost:8000/admin/ (using "roa_user" as login and "roa" as password), and add some pages to the distant database, they'll be listed in the client application at http://localhost:8000/