2011-01-30 14:00:20 +03:00
Django REST framework
=====================
2011-01-17 20:34:58 +03:00
2011-01-30 14:00:20 +03:00
A lightweight REST framework for Django.
2011-01-17 20:34:58 +03:00
2011-01-30 14:00:20 +03:00
Features:
2011-01-24 21:59:23 +03:00
2011-01-24 02:08:16 +03:00
* Clean, simple, class-based views for Resources.
2011-01-24 21:59:23 +03:00
* Support for ModelResources with nice default implementations and input validation.
* Automatically provides a browse-able self-documenting API.
* Pluggable Emitters, Parsers and Authenticators - Easy to customise.
* Content type negotiation using Accept headers.
* Optional support for forms as input validation.
* Modular architecture - Easy to extend and modify.
2011-01-24 02:08:16 +03:00
2011-01-30 19:51:06 +03:00
Requirements
------------
* Python 2.6
* Django 1.2
.. note ::
Support for a wider range of Python & Django versions is planned, but right now django-rest-framework is only tested against these versions.
2011-01-28 20:42:57 +03:00
Installation & Setup
--------------------
2011-01-30 14:00:20 +03:00
The django-rest-framework project is hosted as a `mercurial repository on bitbucket <https://bitbucket.org/tomchristie/flywheel> `_ .
To get a local copy of the repository use mercurial::
hg clone https://tomchristie@bitbucket.org/tomchristie/flywheel
To add django-rest-framework to a django project:
* Copy or symlink the `` djangorestframework `` directory into python's `` site-packages `` directory, or otherwise ensure that the `` djangorestframework `` directory is on your `` PYTHONPATH `` .
* Add `` djangorestframework `` to your `` INSTALLED_APPS `` .
* Ensure the `` TEMPLATE_LOADERS `` setting contains the item `` 'django.template.loaders.app_directories.Loader' `` . (It will do by default, so you shouldn't normally need to do anything here.)
2011-01-28 20:42:57 +03:00
Getting Started
---------------
2011-01-30 14:00:20 +03:00
Often you'll want parts of your API to directly map to existing Models.
At it's simplest this looks something like this...
`` views.py `` ::
from djangorestframework.modelresource import ModelResource, ModelRootResource
from models import MyModel
class MyModelRootResource(ModelRootResource):
"""A create/list resource for MyModel."""
allowed_methods = ('GET', 'POST')
model = MyModel
class MyModelResource(ModelResource):
"""A read/update/delete resource for MyModel."""
allowed_methods = ('GET', 'PUT', 'DELETE')
model = MyModel
`` urls.py `` ::
urlpatterns += patterns('myapp.views',
url(r'^mymodel/$', 'MyModelRootResource'),
url(r'^mymodel/([^/]+)/$', 'MyModelResource'),
)
2011-01-28 20:42:57 +03:00
Examples
--------
2011-01-30 14:00:20 +03:00
There's a few real world examples included with django-rest-framework.
These demonstrate the following use cases:
#. Using :class: `.Resource` for resources that do not map to models.
#. Using :class: `.Resource` with forms for input validation.
#. Using :class: `.ModelResource` for resources that map directly to models.
All the examples are freely available for testing in the sandbox here: http://api.django-rest-framework.org
.. toctree ::
:maxdepth: 1
examples/objectstore
examples/pygments
examples/blogpost
How Tos
-------
.. toctree ::
:maxdepth: 2
howto/usingcurl
2011-01-28 20:42:57 +03:00
2011-01-30 14:00:20 +03:00
.. note ::
2011-01-28 20:42:57 +03:00
2011-01-30 14:00:20 +03:00
TODO
2011-01-28 20:42:57 +03:00
Library Reference
-----------------
2011-01-24 02:08:16 +03:00
.. toctree ::
2011-01-28 20:42:57 +03:00
:maxdepth: 2
2011-01-24 02:08:16 +03:00
2011-01-30 14:00:20 +03:00
library/resource
library/modelresource
library/emitters
library/parsers
library/authenticators
library/response
2011-01-24 02:08:16 +03:00
2011-01-17 20:34:58 +03:00
Indices and tables
------------------
* :ref: `genindex`
* :ref: `modindex`
* :ref: `search`