outcoldman / django-backbone

This app provides a Backbone.js compatible REST API for your models. It follows the Django admin pattern of extending, overriding and registering; and provides an extendable class based view for customization.

django-backbone

Overview

This app provides a Backbone.js compatible REST API for your models. It follows the Django admin pattern of extending, overriding and registering; and provides an extendable class based view for customization.

This way you can have quick, out-of-the-box functionality or you can override any method or variable to customize things to your liking.

For example:

# fooapp/backbone_api.py
import backbone
from fooapp.models import Foo

class FooAPIView(backbone.views.BackboneAPIView):
    model = Foo
    display_fields = ('title', 'description')
    ordering = ('creation_date', 'id')

backbone.site.register(FooAPIView)

More advanced customization can be accomplished by hooking into methods on the inherited class - which itself is a class based view. For example:

...

class FooAPIView(backbone.views.BackboneAPIView):
    model = Foo
    display_fields = ('title', 'description',)
    ordering = ('creation_date', 'id')

    def post(self, request):
        return HttpResponseForbidden('No adding allowed!')

    def queryset(self, request):
        # Only return "active" objects
        return Foo.objects.filter(is_active=True).order_by('-id')

    def has_delete_permission(request, obj):
        return request.user.is_staff  # Only staff can delete objects
...

Features

• Automatically generates a JSON REST API for your models that works nicely with Backbone.js.
• API based on class based views and model forms allowing for fine-grained customization and extensibility.
• Customizable permission restrictions. By default it uses django.contrib.auth authentication and permissions (similar to Django admin).

Usage

1. Create a backbone_api.py file in your app folder and register your API definitions by subclassing backbone.views.BackboneAPIView.

   # fooapp/backbone_api.py
   import backbone
   from fooapp.models import Foo
   
   class FooAPIView(backbone.views.BackboneAPIView):
       model = Foo
       display_fields = ('title', 'description')
       ordering = ('creation_date', 'id')
   
   backbone.site.register(FooAPIView)
   
   See section on 'BackboneAPIView Options' for a full list of options available.
   

2. In your Javascript collection/model definitions, set the url/urlRoot to point to the django-backbone API:

   // Assuming you have a Backbone model called 'Foo' and a collection 'FooCollection'
   Foo.prototype.urlRoot = "{% url 'backbone:fooapp_foo' %}";
   FooCollection.prototype.url = "{% url 'backbone:fooapp_foo' %}";
   
   See section on 'URL reversing' below for details on the url naming.
   

3. (Optional) If your have csrf protection turned on, you'll need to modify the Backbone.sync command to send the csrf token:

   <script>
       // (Optional) Do this if you are using csrf protection:
       // See: https://docs.djangoproject.com/en/dev/ref/contrib/csrf/
       var oldSync = Backbone.sync;
       Backbone.sync = function(method, model, options) {
           options.beforeSend = function(xhr){
               xhr.setRequestHeader('X-CSRFToken', '{{ csrf_token }}');
           };
           return oldSync(method, model, options);
       };
   </script>
   

4. That's it. You should now be able to perform fetch(), save(), etc. on your Backbone collections and models.

Permissions

By default, django-backbone prevents add, update or delete requests unless the user is logged in and has the can_add, can_change or can_delete permission (respectively). This follows the permissions used in the Django admin, with one exception - read access is permitted publicly on all registered models.

This can be changed by overriding the appropriate permission hooks (see section 'BackboneAPIView Options').

BackboneAPIView Options

Please check out the source code of the class backbone.views.BackboneAPIView for the full list of hooks. The methods are documented by their docstrings.

Here are some basic options that you can customize:

• model: The model to be used for this API definition
• display_fields: Fields to return for read (GET) requests,
• fields: Fields to allow when adding (POST) or editing (PUT) objects.
• form: The form class to be used for adding or editing objects.
• ordering: Ordering used when retrieving the collection
• paginate_by: The max number of objects per page (enables use of the page GET parameter).

Reversing the API urls

The following named URL patterns are provided for all models that are registered:

• Collection URL: backbone:<app_name>_<model_name> (reverses to /<app_name>/<model_name>/)
• Model URL: backbone:<app_name>_<model_name>_detail (reverses to /<app_name>/<model_name>/<object_id>)

You can change the <model_name> in the url (and url name) by specifying the url_slug attribute on the BackboneView class (just be sure it doesn't collide with another view).

Installation

Note: django-backbone requires Django 1.3 or higher.

1. Add backbone to INSTALLED_APPS in your settings file.

2. Hook in the urls and call backbone.autodiscover() (which will find all backbone_api.py files in your apps):

   # urls.py
   
   import backbone
   backbone.autodiscover()
   
   urlpatterns += patterns('',
       (r'^backbone/', include(backbone.site.urls)),
   )
   

Running the tests

./manage.py test tests --settings=backbone.tests.settings

Alternatives/Inspiration

This app borrows concepts and patterns from other open source Django/Backbone integration apps. It's worth having a look at them as they may be better suited depending on your use case:

• djangbone: Light weight, simliar concept using class based views.
• backbone-tastypie: A little heavier as it uses django-tastypie which can provide some powerful API features such as throttling and caching.

License

This app is licensed under the BSD license. See the LICENSE file for details.