diff options
| -rw-r--r-- | docs/examples/blogpost.rst | 22 | ||||
| -rw-r--r-- | docs/examples/modelviews.rst (renamed from docs/examples/modelresources.rst) | 22 | ||||
| -rw-r--r-- | docs/examples/views.rst (renamed from docs/examples/resources.rst) | 18 | ||||
| -rw-r--r-- | docs/index.rst | 14 | ||||
| -rw-r--r-- | examples/resourceexample/urls.py | 6 | ||||
| -rw-r--r-- | examples/resourceexample/views.py | 33 |
6 files changed, 56 insertions, 59 deletions
diff --git a/docs/examples/blogpost.rst b/docs/examples/blogpost.rst index 9d762f52..36b9d982 100644 --- a/docs/examples/blogpost.rst +++ b/docs/examples/blogpost.rst @@ -8,26 +8,22 @@ Blog Posts API The models ---------- +In this example we're working from two related models: + ``models.py`` .. include:: ../../examples/blogpost/models.py :literal: -URL configuration ------------------ - -``urls.py`` - -.. include:: ../../examples/blogpost/urls.py - :literal: - Creating the resources ---------------------- -Once we have some existing models there's very little we need to do to create the corresponding resources. We simply create a base resource and an instance resource for each model we're working with. -django-rest-framework will provide the default operations on the resources all the usual input validation that Django's models can give us for free. +Once we have some existing models there's very little we need to do to create the API. +Firstly create a resource for each model that defines which fields we want to expose on the model. +Secondly we map a base view and an instance view for each resource. +The generic views :class:`.ListOrCreateModelView` and :class:`.InstanceModelView` provide default operations for listing, creating and updating our models via the API, and also automatically provide input validation using default ModelForms for each model. -#``views.py`` +``urls.py`` -#.. include:: ../../examples/blogpost/views.py -# :literal:
\ No newline at end of file +.. include:: ../../examples/blogpost/urls.py + :literal: diff --git a/docs/examples/modelresources.rst b/docs/examples/modelviews.rst index 375e4a8d..7cc78d39 100644 --- a/docs/examples/modelresources.rst +++ b/docs/examples/modelviews.rst @@ -1,7 +1,7 @@ -.. _modelresources: +.. _modelviews: -Getting Started - Model Resources ---------------------------------- +Getting Started - Model Views +----------------------------- .. note:: @@ -15,21 +15,21 @@ Getting Started - Model Resources Often you'll want parts of your API to directly map to existing django models. Django REST framework handles this nicely for you in a couple of ways: -#. It automatically provides suitable create/read/update/delete methods for your resources. +#. It automatically provides suitable create/read/update/delete methods for your views. #. Input validation occurs automatically, by using appropriate `ModelForms <http://docs.djangoproject.com/en/dev/topics/forms/modelforms/>`_. -We'll start of defining two resources in our urlconf again. +Here's the model we're working from in this example: -``urls.py`` +``models.py`` -.. include:: ../../examples/modelresourceexample/urls.py +.. include:: ../../examples/modelresourceexample/models.py :literal: -Here's the models we're working from in this example. It's usually a good idea to make sure you provide the :func:`get_absolute_url()` `permalink <http://docs.djangoproject.com/en/dev/ref/models/instances/#get-absolute-url>`_ for all models you want to expose via the API. +To add an API for the model, all we need to do is create a Resource for the model, and map a couple of views to it in our urlconf. -``models.py`` +``urls.py`` -.. include:: ../../examples/modelresourceexample/models.py +.. include:: ../../examples/modelresourceexample/urls.py :literal: And we're done. We've now got a fully browseable API, which supports multiple input and output media types, and has all the nice automatic field validation that Django gives us for free. @@ -49,5 +49,3 @@ Or access it from the command line using curl: # Demonstrates API's input validation using JSON input bash: curl -X POST -H 'Content-Type: application/json' --data-binary '{"foo":true}' http://api.django-rest-framework.org/model-resource-example/ {"detail": {"bar": ["This field is required."], "baz": ["This field is required."]}} - -We could also have added the handler methods :meth:`.Resource.get()`, :meth:`.Resource.post()` etc... seen in the last example, but Django REST framework provides nice default implementations for us that do exactly what we'd expect them to. diff --git a/docs/examples/resources.rst b/docs/examples/views.rst index f3242421..59e13976 100644 --- a/docs/examples/resources.rst +++ b/docs/examples/views.rst @@ -1,7 +1,7 @@ -.. _resources: +.. _views: -Getting Started - Resources ---------------------------- +Getting Started - Views +----------------------- .. note:: @@ -15,12 +15,12 @@ Getting Started - Resources We're going to start off with a simple example, that demonstrates a few things: -#. Creating resources. -#. Linking resources. -#. Writing method handlers on resources. -#. Adding form validation to resources. +#. Creating views. +#. Linking views. +#. Writing method handlers on views. +#. Adding form validation to views. -First we'll define two resources in our urlconf. +First we'll define two views in our urlconf. ``urls.py`` @@ -34,7 +34,7 @@ Now we'll add a form that we'll use for input validation. This is completely op .. include:: ../../examples/resourceexample/forms.py :literal: -Now we'll write our resources. The first is a read only resource that links to three instances of the second. The second resource just has some stub handler methods to help us see that our example is working. +Now we'll write our views. The first is a read only view that links to three instances of the second. The second view just has some stub handler methods to help us see that our example is working. ``views.py`` diff --git a/docs/index.rst b/docs/index.rst index 866ad444..dfa361bd 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -89,17 +89,17 @@ Using Django REST framework can be as simple as adding a few lines to your urlco Django REST framework comes with two "getting started" examples. -#. :ref:`resources` -#. :ref:`modelresources` +#. :ref:`views` +#. :ref:`modelviews` Examples -------- There are a few real world web API examples included with Django REST framework. -#. :ref:`objectstore` - Using :class:`.Resource` for resources that do not map to models. -#. :ref:`codehighlighting` - Using :class:`.Resource` with forms for input validation. -#. :ref:`blogposts` - Using :class:`.ModelResource` for resources that map directly to models. +#. :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. All the examples are freely available for testing in the sandbox: @@ -143,8 +143,8 @@ Examples Reference .. toctree:: :maxdepth: 1 - examples/resources - examples/modelresources + examples/views + examples/modelviews examples/objectstore examples/pygments examples/blogpost diff --git a/examples/resourceexample/urls.py b/examples/resourceexample/urls.py index cb6435bb..452cc92b 100644 --- a/examples/resourceexample/urls.py +++ b/examples/resourceexample/urls.py @@ -1,7 +1,7 @@ from django.conf.urls.defaults import patterns, url -from resourceexample.views import ExampleResource, AnotherExampleResource +from resourceexample.views import ExampleView, AnotherExampleView urlpatterns = patterns('', - url(r'^$', ExampleResource.as_view(), name='example-resource'), - url(r'^(?P<num>[0-9]+)/$', AnotherExampleResource.as_view(), name='another-example-resource'), + url(r'^$', ExampleView.as_view(), name='example'), + url(r'^(?P<num>[0-9]+)/$', AnotherExampleView.as_view(), name='another-example'), ) diff --git a/examples/resourceexample/views.py b/examples/resourceexample/views.py index 29651fbf..990c7834 100644 --- a/examples/resourceexample/views.py +++ b/examples/resourceexample/views.py @@ -1,42 +1,45 @@ from django.core.urlresolvers import reverse from djangorestframework.views import View -from djangorestframework.resources import FormResource from djangorestframework.response import Response from djangorestframework import status from resourceexample.forms import MyForm -class MyFormValidation(FormResource): - """ - A resource which applies form validation on the input. - """ - form = MyForm - -class ExampleResource(View): +class ExampleView(View): """ - A basic read-only resource that points to 3 other resources. + A basic read-only view that points to 3 other views. """ def get(self, request): - return {"Some other resources": [reverse('another-example-resource', kwargs={'num':num}) for num in range(3)]} + """ + Handle GET requests, returning a list of URLs pointing to 3 other views. + """ + return {"Some other resources": [reverse('another-example', kwargs={'num':num}) for num in range(3)]} -class AnotherExampleResource(View): +class AnotherExampleView(View): """ - A basic GET-able/POST-able resource. + A basic view, that can be handle GET and POST requests. + Applies some simple form validation on POST requests. """ - resource = MyFormValidation + form = MyForm def get(self, request, num): - """Handle GET requests""" + """ + Handle GET requests. + Returns a simple string indicating which view the GET request was for. + """ if int(num) > 2: return Response(status.HTTP_404_NOT_FOUND) return "GET request to AnotherExampleResource %s" % num def post(self, request, num): - """Handle POST requests""" + """ + Handle POST requests, with form validation. + Returns a simple string indicating what content was supplied. + """ if int(num) > 2: return Response(status.HTTP_404_NOT_FOUND) return "POST request to AnotherExampleResource %s, with content: %s" % (num, repr(self.CONTENT)) |