diff options
Diffstat (limited to 'docs/index.md')
| -rw-r--r-- | docs/index.md | 77 |
1 files changed, 68 insertions, 9 deletions
diff --git a/docs/index.md b/docs/index.md index 377da54c..cc960a98 100644 --- a/docs/index.md +++ b/docs/index.md @@ -11,13 +11,17 @@ **Awesome web-browsable 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 powerful and flexible toolkit that makes it easy to build Web APIs. -APIs built using REST framework are fully self-describing and web browsable - a huge useability win for your developers. It also supports a wide range of media types, authentication and permission policies out of the box. +Some reasons you might want to use REST framework: -If you are considering using REST framework for your API, we recommend reading the [REST framework 2 announcement][rest-framework-2-announcement] which gives a good overview of the framework and it's capabilities. +* 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. -There is also a sandbox API you can use for testing purposes, [available here][sandbox]. +There is a live example API for testing purposes, [available here][sandbox]. **Below**: *Screenshot from the browsable API* @@ -46,16 +50,12 @@ The following packages are optional: Install using `pip`, including any optional packages you want... pip install djangorestframework - pip install markdown # Markdown support for the browsable API. - pip install pyyaml # YAML content-type support. + pip install markdown # Markdown support for the browsable API. 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. @@ -73,6 +73,57 @@ If you're intending to use the browsable API you'll probably also want to add RE Note that the URL path can be whatever you want, but you must include `'rest_framework.urls'` with the `'rest_framework'` namespace. +## 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', + + # Use Django's standard `django.contrib.auth` permissions, + # or allow read-only access for unauthenticated users. + 'DEFAULT_PERMISSION_CLASSES': [ + 'rest_framework.permissions.DjangoModelPermissionsOrAnonReadOnly' + ] + } + +Don't forget to make sure you've also added `rest_framework` to your `INSTALLED_APPS`. + +We're ready to create our API now. +Here's our project's root `urls.py` module: + + from django.conf.urls.defaults import url, patterns, include + from django.contrib.auth.models import User, Group + from rest_framework import viewsets, routers + + # ViewSets define the view behavior. + class UserViewSet(viewsets.ModelViewSet): + model = User + + 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) + router.register(r'groups', views.GroupViewSet) + + + # 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')) + ) + ## Quickstart Can't wait to get started? The [quickstart guide][quickstart] is the fastest way to get up and running, and building APIs with REST framework. @@ -86,6 +137,7 @@ The tutorial will walk you through the building blocks that make up REST framewo * [3 - Class based views][tut-3] * [4 - Authentication & permissions][tut-4] * [5 - Relationships & hyperlinked APIs][tut-5] +* [6 - Viewsets & routers][tut-6] ## API Guide @@ -95,6 +147,8 @@ The API guide is your complete reference manual to all the functionality provide * [Responses][response] * [Views][views] * [Generic views][generic-views] +* [Viewsets][viewsets] +* [Routers][routers] * [Parsers][parsers] * [Renderers][renderers] * [Serializers][serializers] @@ -122,6 +176,7 @@ General guides to using REST framework. * [REST, Hypermedia & HATEOAS][rest-hypermedia-hateoas] * [2.0 Announcement][rest-framework-2-announcement] * [2.2 Announcement][2.2-announcement] +* [2.3 Announcement][2.3-announcement] * [Release Notes][release-notes] * [Credits][credits] @@ -197,11 +252,14 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. [tut-3]: tutorial/3-class-based-views.md [tut-4]: tutorial/4-authentication-and-permissions.md [tut-5]: tutorial/5-relationships-and-hyperlinked-apis.md +[tut-6]: tutorial/6-viewsets-and-routers.md [request]: api-guide/requests.md [response]: api-guide/responses.md [views]: api-guide/views.md [generic-views]: api-guide/generic-views.md +[viewsets]: api-guide/viewsets.md +[routers]: api-guide/routers.md [parsers]: api-guide/parsers.md [renderers]: api-guide/renderers.md [serializers]: api-guide/serializers.md @@ -226,6 +284,7 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. [contributing]: topics/contributing.md [rest-framework-2-announcement]: topics/rest-framework-2-announcement.md [2.2-announcement]: topics/2.2-announcement.md +[2.3-announcement]: topics/2.3-announcement.md [release-notes]: topics/release-notes.md [credits]: topics/credits.md |