From 3531b0b35540ade216299c46717dcf9fa24487c7 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Thu, 2 Jun 2011 16:03:11 +0100 Subject: More updating docs for 0.2 --HG-- rename : docs/examples/modelresources.rst => docs/examples/modelviews.rst rename : docs/examples/resources.rst => docs/examples/views.rst --- docs/examples/blogpost.rst | 22 ++++++--------- docs/examples/modelresources.rst | 53 ----------------------------------- docs/examples/modelviews.rst | 51 ++++++++++++++++++++++++++++++++++ docs/examples/resources.rst | 58 --------------------------------------- docs/examples/views.rst | 58 +++++++++++++++++++++++++++++++++++++++ docs/index.rst | 14 +++++----- examples/resourceexample/urls.py | 6 ++-- examples/resourceexample/views.py | 33 ++++++++++++---------- 8 files changed, 146 insertions(+), 149 deletions(-) delete mode 100644 docs/examples/modelresources.rst create mode 100644 docs/examples/modelviews.rst delete mode 100644 docs/examples/resources.rst create mode 100644 docs/examples/views.rst 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/modelresources.rst deleted file mode 100644 index 375e4a8d..00000000 --- a/docs/examples/modelresources.rst +++ /dev/null @@ -1,53 +0,0 @@ -.. _modelresources: - -Getting Started - Model Resources ---------------------------------- - -.. note:: - - A live sandbox instance of this API is available: - - http://api.django-rest-framework.org/model-resource-example/ - - You can browse the API using a web browser, or from the command line:: - - curl -X GET http://api.django-rest-framework.org/resource-example/ -H 'Accept: text/plain' - -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. -#. Input validation occurs automatically, by using appropriate `ModelForms `_. - -We'll start of defining two resources in our urlconf again. - -``urls.py`` - -.. include:: ../../examples/modelresourceexample/urls.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 `_ for all models you want to expose via the API. - -``models.py`` - -.. include:: ../../examples/modelresourceexample/models.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. - -We can visit the API in our browser: - -* http://api.django-rest-framework.org/model-resource-example/ - -Or access it from the command line using curl: - -.. code-block:: bash - - # Demonstrates API's input validation using form input - bash: curl -X POST --data 'foo=true' http://api.django-rest-framework.org/model-resource-example/ - {"detail": {"bar": ["This field is required."], "baz": ["This field is required."]}} - - # 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/modelviews.rst b/docs/examples/modelviews.rst new file mode 100644 index 00000000..7cc78d39 --- /dev/null +++ b/docs/examples/modelviews.rst @@ -0,0 +1,51 @@ +.. _modelviews: + +Getting Started - Model Views +----------------------------- + +.. note:: + + A live sandbox instance of this API is available: + + http://api.django-rest-framework.org/model-resource-example/ + + You can browse the API using a web browser, or from the command line:: + + curl -X GET http://api.django-rest-framework.org/resource-example/ -H 'Accept: text/plain' + +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 views. +#. Input validation occurs automatically, by using appropriate `ModelForms `_. + +Here's the model we're working from in this example: + +``models.py`` + +.. include:: ../../examples/modelresourceexample/models.py + :literal: + +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. + +``urls.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. + +We can visit the API in our browser: + +* http://api.django-rest-framework.org/model-resource-example/ + +Or access it from the command line using curl: + +.. code-block:: bash + + # Demonstrates API's input validation using form input + bash: curl -X POST --data 'foo=true' http://api.django-rest-framework.org/model-resource-example/ + {"detail": {"bar": ["This field is required."], "baz": ["This field is required."]}} + + # 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."]}} diff --git a/docs/examples/resources.rst b/docs/examples/resources.rst deleted file mode 100644 index f3242421..00000000 --- a/docs/examples/resources.rst +++ /dev/null @@ -1,58 +0,0 @@ -.. _resources: - -Getting Started - Resources ---------------------------- - -.. note:: - - A live sandbox instance of this API is available: - - http://api.django-rest-framework.org/resource-example/ - - You can browse the API using a web browser, or from the command line:: - - curl -X GET http://api.django-rest-framework.org/resource-example/ -H 'Accept: text/plain' - -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. - -First we'll define two resources in our urlconf. - -``urls.py`` - -.. include:: ../../examples/resourceexample/urls.py - :literal: - -Now we'll add a form that we'll use for input validation. This is completely optional, but it's often useful. - -``forms.py`` - -.. 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. - -``views.py`` - -.. include:: ../../examples/resourceexample/views.py - :literal: - -That's us done. Our API now provides both programmatic access using JSON and XML, as well a nice browseable HTML view, so we can now access it both from the browser: - -* http://api.django-rest-framework.org/resource-example/ - -And from the command line: - -.. code-block:: bash - - # Demonstrates API's input validation using form input - bash: curl -X POST --data 'foo=true' http://api.django-rest-framework.org/resource-example/1/ - {"detail": {"bar": ["This field is required."], "baz": ["This field is required."]}} - - # 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/resource-example/1/ - {"detail": {"bar": ["This field is required."], "baz": ["This field is required."]}} diff --git a/docs/examples/views.rst b/docs/examples/views.rst new file mode 100644 index 00000000..59e13976 --- /dev/null +++ b/docs/examples/views.rst @@ -0,0 +1,58 @@ +.. _views: + +Getting Started - Views +----------------------- + +.. note:: + + A live sandbox instance of this API is available: + + http://api.django-rest-framework.org/resource-example/ + + You can browse the API using a web browser, or from the command line:: + + curl -X GET http://api.django-rest-framework.org/resource-example/ -H 'Accept: text/plain' + +We're going to start off with a simple example, that demonstrates a few things: + +#. Creating views. +#. Linking views. +#. Writing method handlers on views. +#. Adding form validation to views. + +First we'll define two views in our urlconf. + +``urls.py`` + +.. include:: ../../examples/resourceexample/urls.py + :literal: + +Now we'll add a form that we'll use for input validation. This is completely optional, but it's often useful. + +``forms.py`` + +.. include:: ../../examples/resourceexample/forms.py + :literal: + +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`` + +.. include:: ../../examples/resourceexample/views.py + :literal: + +That's us done. Our API now provides both programmatic access using JSON and XML, as well a nice browseable HTML view, so we can now access it both from the browser: + +* http://api.django-rest-framework.org/resource-example/ + +And from the command line: + +.. code-block:: bash + + # Demonstrates API's input validation using form input + bash: curl -X POST --data 'foo=true' http://api.django-rest-framework.org/resource-example/1/ + {"detail": {"bar": ["This field is required."], "baz": ["This field is required."]}} + + # 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/resource-example/1/ + {"detail": {"bar": ["This field is required."], "baz": ["This field is required."]}} 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[0-9]+)/$', AnotherExampleResource.as_view(), name='another-example-resource'), + url(r'^$', ExampleView.as_view(), name='example'), + url(r'^(?P[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)) -- cgit v1.2.3