diff options
| -rw-r--r-- | README.md | 61 | ||||
| -rw-r--r-- | docs/index.md | 5 |
2 files changed, 37 insertions, 29 deletions
@@ -24,34 +24,20 @@ If you are considering using REST framework for your API, we recommend reading t There is also a sandbox API you can use for testing purposes, [available here][sandbox]. +**Below**: *Screenshot from the browseable API* + +![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,20 +55,42 @@ 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. -To build the docs. +We'll create a read-write API for accessing users and groups. - ./mkdocs.py +Here's our project's root `urls.py` module: -To run the tests. + from django.conf.urls.defaults import url, patterns, include + from django.contrib.auth.models import User, Group + from rest_framework import viewsets, routers - ./rest_framework/runtests/runtests.py + # ViewSets define the view behavior. + class UserViewSet(viewsets.ModelViewSet): + model = User -To run the tests against all supported configurations, first install [the tox testing tool][tox] globally, using `pip install tox`, then simply run `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')) + ) - tox +# Documentation +The full documentation for the project is available at [http://django-rest-framework.org][docs]. # License Copyright (c) 2011-2013, Tom Christie @@ -116,6 +124,7 @@ 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/ diff --git a/docs/index.md b/docs/index.md index 12e39153..19ed5a98 100644 --- a/docs/index.md +++ b/docs/index.md @@ -11,7 +11,7 @@ **Awesome web-browseable Web APIs.** -Django REST framework is a flexible, powerful Web API toolkit. It is designed as a modular and easy to customize architecture, based on Django's class based views. +Django REST framework is a flexible and powerful Web API toolkit. It is designed as a modular and easy to customize architecture, based on Django's class based views. 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. @@ -46,8 +46,7 @@ The following packages are optional: Install using `pip`, including any optional packages you want... pip install djangorestframework - pip install markdown # Markdown support for the browseable API. - pip install pyyaml # YAML content-type support. + pip install markdown # Markdown support for the browseable API. pip install django-filter # Filtering support ...or clone the project from github. |