Source

django-repose / Readme.txt

Full commit
# repose - a RESTful django framework #

## Why repose? Why another framework? ##

This is not the first time I've written a framework for creating a RESTful interface from django. The first attempt, called `rest_api` was modelled on the django admin interface (`django.contrib.admin`), and was used in a work project extensively.

There were lots of bits I didn't like about it. Some of this I didn't even realize until I came across `django-rest-framework`: which uses django forms for validation.

I decided to take this even further.

Repose is a form-based rest-api framework.

That is, the intention is that you will use django's forms to create and render your views, even if they are JSON or XML.

## Installation ##

You'll want to install repose into your virtualenv.


## Usage ##

Repose uses the django class-based-views structure. In fact, the views within repose all inherit from `django.views.generic.View`.

Repose provides a handful of pre-built views, but the general idea is that you will probably want to sub-class them.

The simplest way to use a repose view is to install it in your urls.py as follows:

    from repose.views import ModelDetailView
    
    from models import ModelName
    
    urlpatterns = patterns('',
        url(r'^path/$', ModelDetailView.as_view(model=ModelName), name="modelname_detail"),
    )

This will automatically create a ModelForm (which also includes the 'id' field, allowing the client to know about relationships without having to embed them).


You can supply your own Form, and/or View classes:

    from repose.views import ModelDetailView
    from models import ModelName
    from forms import ModelNameForm
    
    class ModelNameView(ModelDetailView):
        form = ModelNameForm
        
You may also override some specific methods in your View class to change behaviour. The most common is likely to be ``get_queryset``, which enables you you change which subset of objects ``request.user`` is able to access. For the detail view classes, you can also override ``get_object``.


There are some useful Mixins that do this type of thing in `mixins.py`