django-rest-framework/docs/index.rst

161 lines
4.7 KiB
ReStructuredText
Raw Normal View History

2011-02-01 22:55:57 +03:00
.. meta::
:description: A lightweight REST framework for Django.
2011-02-19 18:50:40 +03:00
:keywords: django, python, REST, RESTful, API, interface, framework
2011-02-01 22:55:57 +03:00
Django REST framework
=====================
2011-01-17 20:34:58 +03:00
2011-02-02 02:08:18 +03:00
Introduction
------------
Django REST framework is a lightweight REST framework for Django, that aims to make it easy to build well-connected, self-describing RESTful Web APIs.
2011-04-27 21:25:11 +04:00
**Browse example APIs created with Django REST framework:** `The Sandbox <http://api.django-rest-framework.org/>`_
2011-01-17 20:34:58 +03:00
Features:
2011-01-24 21:59:23 +03:00
2011-04-27 21:25:11 +04:00
* Automatically provides an awesome Django admin style `browse-able self-documenting API <http://api.django-rest-framework.org>`_.
2011-02-19 16:12:35 +03:00
* Clean, simple, views for Resources, using Django's new `class based views <http://docs.djangoproject.com/en/dev/topics/class-based-views/>`_.
* Support for ModelResources with out-of-the-box default implementations and input validation.
2011-05-17 12:15:35 +04:00
* Pluggable :mod:`.parsers`, :mod:`renderers`, :mod:`authentication` and :mod:`permissions` - Easy to customise.
2011-02-19 16:12:35 +03:00
* Content type negotiation using HTTP Accept headers.
2011-01-24 21:59:23 +03:00
* Optional support for forms as input validation.
2011-02-19 18:50:40 +03:00
* Modular architecture - MixIn classes can be used without requiring the :class:`.Resource` or :class:`.ModelResource` classes.
2011-02-19 16:12:35 +03:00
2011-04-27 21:25:11 +04:00
Resources
---------
2011-02-19 16:12:35 +03:00
2011-04-27 21:25:11 +04:00
**Project hosting:** `Bitbucket <https://bitbucket.org/tomchristie/django-rest-framework>`_ and `GitHub <https://github.com/tomchristie/django-rest-framework>`_.
2011-04-27 21:25:11 +04:00
* The ``djangorestframework`` package is `available on PyPI <http://pypi.python.org/pypi/djangorestframework>`_.
* We have an active `discussion group <http://groups.google.com/group/django-rest-framework>`_ and a `project blog <http://blog.django-rest-framework.org>`_.
2011-06-02 16:34:23 +04:00
* Bug reports are handled on the `issue tracker <https://github.com/tomchristie/django-rest-framework/issues>`_.
2011-04-27 21:25:11 +04:00
* There is a `Jenkins CI server <http://datacenter.tibold.nl/job/djangorestframework/>`_ which tracks test status and coverage reporting. (Thanks Marko!)
2011-02-22 01:21:49 +03:00
2011-04-27 21:25:11 +04:00
Any and all questions, thoughts, bug reports and contributions are *hugely appreciated*.
2011-01-30 19:51:06 +03:00
Requirements
------------
2011-02-19 16:12:35 +03:00
* Python (2.5, 2.6, 2.7 supported)
* Django (1.2, 1.3 supported)
2011-01-30 19:51:06 +03:00
2011-06-02 16:34:23 +04:00
Installation
------------
2011-02-19 22:15:16 +03:00
2011-02-22 01:21:49 +03:00
You can install Django REST framework using ``pip`` or ``easy_install``::
2011-02-22 03:03:15 +03:00
pip install djangorestframework
2011-02-22 01:21:49 +03:00
2011-04-27 21:25:11 +04:00
Or get the latest development version using mercurial or git::
2011-02-19 22:15:16 +03:00
2011-04-27 21:25:11 +04:00
hg clone https://bitbucket.org/tomchristie/django-rest-framework
git clone git@github.com:tomchristie/django-rest-framework.git
2011-02-19 22:15:16 +03:00
2011-06-02 16:34:23 +04:00
Or you can `download the current release <http://pypi.python.org/pypi/djangorestframework>`_.
2011-02-19 22:15:16 +03:00
2011-06-02 16:34:23 +04:00
Setup
-----
2011-06-02 16:34:23 +04:00
To add Django REST framework to a Django project:
2011-04-27 21:25:11 +04:00
* Ensure that the ``djangorestframework`` directory is on your ``PYTHONPATH``.
* Add ``djangorestframework`` to your ``INSTALLED_APPS``.
2011-06-02 16:34:23 +04:00
For more information on settings take a look at the :ref:`setup` section.
2011-02-02 02:08:18 +03:00
2011-02-19 16:12:35 +03:00
Getting Started
---------------
2011-02-02 11:43:27 +03:00
2011-06-02 18:22:14 +04:00
Using Django REST framework can be as simple as adding a few lines to your urlconf.
2011-02-19 18:50:40 +03:00
2011-06-02 18:22:14 +04:00
``urls.py``::
2011-02-02 02:08:18 +03:00
2011-02-19 16:12:35 +03:00
from django.conf.urls.defaults import patterns, url
2011-06-02 18:22:14 +04:00
from djangorestframework.resources import ModelResource
from djangorestframework.views import ListOrCreateModelView, InstanceModelView
from myapp.models import MyModel
class MyResource(ModelResource):
model = MyModel
2011-02-19 16:12:35 +03:00
urlpatterns = patterns('',
2011-06-02 18:22:14 +04:00
url(r'^$', RootModelResource.as_view(resource=MyResource)),
url(r'^(?P<pk>[^/]+)/$', ModelResource.as_view(resource=MyResource)),
)
2011-02-19 18:50:40 +03:00
2011-02-19 16:12:35 +03:00
Django REST framework comes with two "getting started" examples.
#. :ref:`views`
#. :ref:`modelviews`
2011-02-19 16:12:35 +03:00
Examples
--------
2011-02-19 16:12:35 +03:00
There are a few real world web API examples included with Django REST framework.
#. :ref:`objectstore` - Using :class:`views.View` classes for APIs that do not map to models.
#. :ref:`codehighlighting` - Using :class:`views.View` classes with forms for input validation.
#. :ref:`blogposts` - Using :class:`views.ModelView` classes for APIs that map directly to models.
2011-02-19 16:12:35 +03:00
All the examples are freely available for testing in the sandbox:
2011-02-22 01:23:09 +03:00
http://api.django-rest-framework.org
2011-02-19 16:12:35 +03:00
(The :ref:`sandbox` resource is also documented.)
2011-02-02 11:43:27 +03:00
How Tos, FAQs & Notes
---------------------
.. toctree::
2011-02-19 16:12:35 +03:00
:maxdepth: 1
2011-02-19 16:12:35 +03:00
howto/setup
howto/usingcurl
2011-02-02 11:43:27 +03:00
howto/alternativeframeworks
2011-02-19 16:12:35 +03:00
howto/mixin
Library Reference
-----------------
.. toctree::
2011-02-19 16:12:35 +03:00
:maxdepth: 1
library/authentication
library/compat
library/mixins
library/parsers
library/permissions
library/renderers
library/resource
library/response
2011-02-19 16:12:35 +03:00
library/status
library/views
2011-02-19 16:12:35 +03:00
Examples Reference
------------------
2011-02-19 16:12:35 +03:00
.. toctree::
:maxdepth: 1
examples/views
examples/modelviews
2011-02-19 16:12:35 +03:00
examples/objectstore
examples/pygments
examples/blogpost
examples/sandbox
howto/mixin
2011-01-17 20:34:58 +03:00
Indices and tables
------------------
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`