Getting started with Django-ROA
In order to use remote access with your models, there are 3 steps:
- inherit from
django_roa.Modelfor your models.
- inherit from
django_roa.Managerfor your own managers if you'd like to extend/modify the default one.
- inherit from
django_roa.ModelAdminfor your own admin if you'd like to set custom options.
get_resource_url_liststatic method in your models to access your remote resource in a RESTful way. Optionally, use
get_resource_url_detailmethod for your model in order to define your own detail url, default is
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
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:
INSTALLED_APPS = ( 'django_roa', etc )
ROA_MODELS = Truein your settings.
- specify the mapping of applications' names in your
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:
INSTALLED_APPS = ( 'django_roa', 'django_roa.remoteauth', etc )
AUTHENTICATION_BACKENDS = ( 'django_roa.remoteauth.backends.RemoteUserModelBackend', )
- in this case
ROA_MODEL_NAME_MAPPINGsetting will look like this:
ROA_MODEL_NAME_MAPPING = ( # local name: remote name ('django_roa_client.', 'django_roa_server.'), ('remoteauth.', 'auth.'), )
ROA_URL_OVERRIDES_* settings allow you to customize the URLs requested by this application. See specifications for a more detailed explanation.
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.
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
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/