django-rest-framework/docs/index.rst

129 lines
4.3 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.
**Browse example APIs created with Django REST framework:** `The Sandbox <http://rest.ep.io/>`_
2011-01-17 20:34:58 +03:00
Features:
2012-01-03 00:16:44 +04:00
---------
2011-01-24 21:59:23 +03:00
* Automatically provides an awesome Django admin style `browse-able self-documenting API <http://rest.ep.io>`_.
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
**Project hosting:** `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>`_.
2011-06-02 16:34:23 +04:00
* Bug reports are handled on the `issue tracker <https://github.com/tomchristie/django-rest-framework/issues>`_.
* There is a `Jenkins CI server <http://jenkins.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)
2012-02-21 00:31:41 +04:00
* Django (1.2, 1.3, 1.4 supported)
* `django.contrib.staticfiles`_ (or `django-staticfiles`_ for Django 1.2)
* `URLObject`_ >= 2.0.0
* `Markdown`_ >= 2.1.0 (Optional)
* `PyYAML`_ >= 3.10 (Optional)
2011-01-30 19:51:06 +03:00
2011-06-02 16:34:23 +04:00
Installation
------------
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
2012-01-02 22:31:46 +04:00
Or get the latest development version using git::
2011-02-19 22:15:16 +03:00
2011-04-27 21:25:11 +04:00
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
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``.
* Add the following to your URLconf. (To include the REST framework Login/Logout views.)::
urlpatterns = patterns('',
...
url(r'^restframework', include('djangorestframework.urls', namespace='djangorestframework'))
)
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
The following example exposes your `MyModel` model through an api. It will provide two views:
* A view which lists your model instances and simultaniously allows creation of instances
from that view.
* Another view which lets you view, update or delete your model instances individually.
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
2011-06-02 18:22:14 +04:00
class MyResource(ModelResource):
model = MyModel
2011-02-19 16:12:35 +03:00
urlpatterns = patterns('',
2011-06-09 05:07:46 +04:00
url(r'^$', ListOrCreateModelView.as_view(resource=MyResource)),
url(r'^(?P<pk>[^/]+)/$', InstanceModelView.as_view(resource=MyResource)),
2011-06-02 18:22:14 +04:00
)
2011-02-19 18:50:40 +03:00
.. include:: howto.rst
.. include:: library.rst
.. include:: examples.rst
2011-02-19 16:12:35 +03:00
.. toctree::
:hidden:
contents
.. include:: ../CHANGELOG.rst
2011-01-17 20:34:58 +03:00
Indices and tables
------------------
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
2012-02-21 00:31:41 +04:00
.. _django.contrib.staticfiles: https://docs.djangoproject.com/en/dev/ref/contrib/staticfiles/
.. _django-staticfiles: http://pypi.python.org/pypi/django-staticfiles/
.. _URLObject: http://pypi.python.org/pypi/URLObject/
.. _Markdown: http://pypi.python.org/pypi/Markdown/
.. _PyYAML: http://pypi.python.org/pypi/PyYAML