Skip to main content

Provides a Backbone.js compatible REST API for your models using Django Admin style registration.

Project description


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/
import backbone
from fooapp.models import Foo

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

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


  • 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).


  1. Create a file in your app folder and register your API definitions by subclassing backbone.views.BackboneAPIView.
    # fooapp/
    import backbone
    from fooapp.models import Foo
    class FooAPIView(backbone.views.BackboneAPIView):
        model = Foo
        display_fields = ('title', 'description')
        ordering = ('creation_date', 'id')
    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:
        // (Optional) Do this if you are using csrf protection:
        // See:
        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);
  4. That’s it. You should now be able to perform fetch(), save(), etc. on your Backbone collections and models.


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).


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 files in your apps):
    import backbone
    urlpatterns += patterns('',
        (r'^backbone/', include(,

Running the tests

# For Django 1.6+
./ test backbone.tests --settings=backbone.tests.settings

# For Django < 1.6
./ test tests --settings=backbone.tests.settings


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.


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

Project details

Release history Release notifications

This version
History Node


History Node


History Node


History Node


History Node


History Node


History Node


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
django-backbone-0.3.2.tar.gz (13.1 kB) Copy SHA256 hash SHA256 Source None Jul 29, 2014

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging CloudAMQP CloudAMQP RabbitMQ AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page