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)
    
    @staticmethod
    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.save()
>>> 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()
0

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:

INSTALLED_APPS = (
    'django_roa',
    etc
)

• add ROA_MODELS = True in your settings.

• specify the mapping of applications' names in your ROA_MODEL_NAME_MAPPING setting:

ROA_MODEL_NAME_MAPPING = (
    ('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:

INSTALLED_APPS = (
    'django_roa',
    'django_roa.remoteauth',
    etc
)

• add RemoteUserModelBackend to your AUTHENTICATION_BACKENDS setting:

AUTHENTICATION_BACKENDS = (
    'django_roa.remoteauth.backends.RemoteUserModelBackend',
)

• in this case ROA_MODEL_NAME_MAPPING setting will look like this:

ROA_MODEL_NAME_MAPPING = (
    # 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 manage.py syncdb --noinput

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

    $ python manage.py runserver 8081

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

    $ python manage.py 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.

django_roa_server

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 manage.py syncdb
python manage.py runserver 8081

django_roa_client

Now, launch the client part:

cd examples/django_roa_client
python manage.py syncdb
python manage.py 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/

This revision is from 2012-01-26 05:19