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 ++++++++++++++++++++++++++++++++++++++++ 5 files changed, 118 insertions(+), 124 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 (limited to 'docs/examples') 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."]}} -- cgit v1.2.3