Getting started

Requirements

RIV does not require any additional third party modules. The serializers are built on top of the built-in Django serializers and therefore share the same requirements.

Installation

1. Pull django-riv from GitHub

2. Install using:

   sudo python setup.py install

   This also makes sure the required modules get installed automatically

Configuration

1. Add RiV to the list of your installed apps:

   # settings.py
   INSTALLED_APPS = (
     # ...
     'riv'
   )
   

2. Add the RivMiddleware to the end of your middleware classes:

   # settings.py
   MIDDLEWARE_CLASSES = (
     'django.middleware.common.CommonMiddleware',
     # ...
     'riv.middleware.RivMiddleware'
   )
   

#. The RiV serializers extend the builtin Django serializers. Add them to the list of SERIALIZATION_MODULES:

# settings.py
SERIALIZATION_MODULES = {
  'restjson': 'riv.serializers.json',
  'restxml':  'riv.serializers.xml'
}

#. For debugging purposes you can tell RIV to display errors. However, for security reasons this setting only has an effect if Django is running in debug mode:

# settings.py
RIV_DISPLAY_ERRORS = True

Creating resources

Add a resources.py file to your application and add a resource for each model. Each resource needs to set a wrapper class that links your views to the HTTP methods (will we create them in the next step):

# myapp/resources.py
from riv.resources import Resource
from myapp.models import MyModel, MyOtherModel
from myapp.wrappers import MyModelWrapper, MyOtherModelWrapper

class MyModelResource(Resource):
  _wrapper = MyModelWrapper()
  class Meta:
    name = 'mymodel'
    model = MyModel

class MyOtherModelResource(Resource):
  _wrapper = MyOtherModelWrapper()
  class Meta:
    name = 'myothermodel'
    model = MyOtherModel

Using wrappers to link to views

A wrapper should be derived from the BaseWrapper class. The wrapper can define the following methods:

• read (for GET requests with an id)
• read_multiple (for GET requests without an id or multiple ids)
• create (for POST requests)
• create_multiple (for POST requests containing an array of objects. You have to set the allow_batch_creation option if you want to support this. See the Resources documentation for details)
• update (for PUT requests with an id)
• update_multiple (for PUT requests with multiple ids)
• delete (for DELETE requests with an id)
• delete_multiple (for DELETE requests without an id or multiple ids)

You can link to your existing views using the call_view method. Consider you have the following view:

# myapp/views.py
def mymodel_detail(request, id):
    m = get_object_or_404(MyModel, pk=id)
    return render_to_response('detail.html', {'mymodel': m})

Your wrapper class should look like this:

# myapp/wrappers.py
from riv.wrappers import BaseWrapper
from riv.helpers import call_view
from myapp import views

class MyModelWrapper(BaseWrapper):
    read = call_view(views.mymodel_detail)

Now you need adjust your view to handle calls through the API properly:

# myapp/views.py
...
from riv.shortcuts import render_to_rest

def mymodel_detail(request, id):
    m = get_object_or_404(MyModel, pk=id)
    if request.is_rest():
        return render_to_rest(m)
    return render_to_response('detail.html', {'mymodel': m})

Using the StandaloneWrapper

If you don’t any special data preparation in your views or if you simply don’t have views for your model you can use the StandaloneWrapper to make your model accessible directly:

# myapp/resources.py
from riv.resources import Resource
from riv.wrappers import StandaloneWrapper
from myapp.models import MyModel, MyOtherModel

class MyModelResource(Resource):
  _wrapper = StandaloneWrapper()
  class Meta:
    name = 'mymodel'
    model = MyModel

Setting up the API

The API class is used to bundle several resources together and form a logical unit. Adding the API to your URLconf makes the resources available:

# myapp/urls.py
from riv.api import Api
from myapp.resources import MyModelResource, MyOtherModelResource

# The api name is only used internally. It does not become part
# of your URL
myapi = Api(name='myapi')
myapi.register(MyModelResource())
myapi.register(MyOtherModelResource())

urlpatterns += patterns('',
  (r'api/', include(myapi.urls)),
)

Try it

You can now access the registered resources at:

http://<yourhost>/myapp/api/<resource_name>

In this case:

http://<yourhost>/myapp/api/mymodel
http://<yourhost>/myapp/api/myothermodel