diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 110 |
1 files changed, 71 insertions, 39 deletions
@@ -1,57 +1,39 @@ # Django REST framework -**A toolkit for building well-connected, self-describing web APIs.** - -**Author:** Tom Christie. [Follow me on Twitter][twitter]. - -**Support:** [REST framework group][group], or `#restframework` on freenode IRC. +**Awesome web-browseable Web APIs.** [![build-status-image]][travis] ---- +**Note**: Full documentation for the project is available at [http://django-rest-framework.org][docs]. -**Full documentation for REST framework is available on [http://django-rest-framework.org][docs].** +# Overview ---- +Django REST framework is a powerful and flexible toolkit that makes it easy to build Web APIs. -# Overview +Some reasons you might want to use REST framework: -Django REST framework is a lightweight library that makes it easy to build Web APIs. It is designed as a modular and easy to customize architecture, based on Django's class based views. +* The Web browseable API is a huge useability win for your developers. +* Authentication policies including OAuth1a and OAuth2 out of the box. +* Serialization that supports both ORM and non-ORM data sources. +* Customizable all the way down - just use regular function-based views if you don't need the more powerful features. +* Extensive documentation, and great community support. -Web APIs built using REST framework are fully self-describing and web browseable - a huge useability win for your developers. It also supports a wide range of media types, authentication and permission policies out of the box. +There is a live example API for testing purposes, [available here][sandbox]. -If you are considering using REST framework for your API, we recommend reading the [REST framework 2 announcment][rest-framework-2-announcement] which gives a good overview of the framework and it's capabilities. +**Below**: *Screenshot from the browseable API* -There is also a sandbox API you can use for testing purposes, [available here][sandbox]. +![Screenshot][image] # Requirements * Python (2.6.5+, 2.7, 3.2, 3.3) * Django (1.3, 1.4, 1.5) -**Optional:** - -* [Markdown][markdown] - Markdown support for the self describing API. -* [PyYAML][pyyaml] - YAML content type support. -* [defusedxml][defusedxml] - XML content-type support. -* [django-filter][django-filter] - Filtering support. - # Installation -Install using `pip`, including any optional packages you want... +Install using `pip`... pip install djangorestframework - pip install markdown # Markdown support for the browseable API. - pip install pyyaml # YAML content-type support. - pip install defusedxml # XML content-type support. - pip install django-filter # Filtering support - -...or clone the project from github. - - git clone git@github.com:tomchristie/django-rest-framework.git - cd django-rest-framework - pip install -r requirements.txt - pip install -r optionals.txt Add `'rest_framework'` to your `INSTALLED_APPS` setting. @@ -69,19 +51,64 @@ If you're intending to use the browseable API you'll probably also want to add R Note that the URL path can be whatever you want, but you must include `'rest_framework.urls'` with the `'rest_framework'` namespace. -# Development +# Example + +Let's take a look at a quick example of using REST framework to build a simple model-backed API. + +We'll create a read-write API for accessing users and groups. + +Any global settings for a REST framework API are kept in a single configuration dictionary named `REST_FRAMEWORK`. Start off by adding the following to your `settings.py` module: + + REST_FRAMEWORK = { + # Use hyperlinked styles by default. + # Only used if the `serializer_class` attribute is not set on a view. + 'DEFAULT_MODEL_SERIALIZER_CLASS': + 'rest_framework.serializers.HyperlinkedModelSerializer', -To build the docs. + # Use Django's standard `django.contrib.auth` permissions, + # or allow read-only access for unauthenticated users. + 'DEFAULT_PERMISSION_CLASSES': [ + 'rest_framework.permissions.DjangoModelPermissionsOrAnonReadOnly' + ] + } - ./mkdocs.py +Don't forget to make sure you've also added `rest_framework` to your `INSTALLED_APPS`. -To run the tests. +We're ready to create our API now. +Here's our project's root `urls.py` module: - ./rest_framework/runtests/runtests.py + from django.conf.urls.defaults import url, patterns, include + from django.contrib.auth.models import User, Group + from rest_framework import viewsets, routers -To run the tests against all supported configurations, first install [the tox testing tool][tox] globally, using `pip install tox`, then simply run `tox`: + # ViewSets define the view behavior. + class UserViewSet(viewsets.ModelViewSet): + model = User - tox + class GroupViewSet(viewsets.ModelViewSet): + model = Group + + + # Routers provide an easy way of automatically determining the URL conf + router = routers.DefaultRouter() + router.register(r'users', views.UserViewSet, name='user') + router.register(r'groups', views.GroupViewSet, name='group') + + + # Wire up our API using automatic URL routing. + # Additionally, we include login URLs for the browseable API. + urlpatterns = patterns('', + url(r'^', include(router.urls)), + url(r'^api-auth/', include('rest_framework.urls', namespace='rest_framework')) + ) + +# Documentation & Support + +Full documentation for the project is available at [http://django-rest-framework.org][docs]. + +For questions and support, use the [REST framework discussion group][group], or `#restframework` on freenode IRC. + +You may also want to [follow the author on Twitter][twitter]. # License @@ -116,9 +143,14 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. [sandbox]: http://restframework.herokuapp.com/ [rest-framework-2-announcement]: http://django-rest-framework.org/topics/rest-framework-2-announcement.html [2.1.0-notes]: https://groups.google.com/d/topic/django-rest-framework/Vv2M0CMY9bg/discussion +[image]: http://django-rest-framework.org/img/quickstart.png [tox]: http://testrun.org/tox/latest/ +[tehjones]: https://twitter.com/tehjones/status/294986071979196416 +[wlonk]: https://twitter.com/wlonk/status/261689665952833536 +[laserllama]: https://twitter.com/laserllama/status/328688333750407168 + [docs]: http://django-rest-framework.org/ [urlobject]: https://github.com/zacharyvoase/urlobject [markdown]: http://pypi.python.org/pypi/Markdown/ |