diff options
Diffstat (limited to 'docs/examples')
| -rw-r--r-- | docs/examples/blogpost.rst | 37 | ||||
| -rw-r--r-- | docs/examples/modelviews.rst | 56 | ||||
| -rw-r--r-- | docs/examples/objectstore.rst | 17 | ||||
| -rw-r--r-- | docs/examples/permissions.rst | 66 | ||||
| -rw-r--r-- | docs/examples/pygments.rst | 89 | ||||
| -rw-r--r-- | docs/examples/sandbox.rst | 12 | ||||
| -rw-r--r-- | docs/examples/views.rst | 56 |
7 files changed, 0 insertions, 333 deletions
diff --git a/docs/examples/blogpost.rst b/docs/examples/blogpost.rst deleted file mode 100644 index 11e376ef..00000000 --- a/docs/examples/blogpost.rst +++ /dev/null @@ -1,37 +0,0 @@ -Blog Posts API -============== - -* http://rest.ep.io/blog-post/ - -The models ----------- - -In this example we're working from two related models: - -``models.py`` - -.. include:: ../../examples/blogpost/models.py - :literal: - -Creating the resources ----------------------- - -We need to create two resources that we map to our two existing models, in order to describe how the models should be serialized. -Our resource descriptions will typically go into a module called something like 'resources.py' - -``resources.py`` - -.. include:: ../../examples/blogpost/resources.py - :literal: - -Creating views for our resources --------------------------------- - -Once we've created the resources there's very little we need to do to create the API. -For each resource we'll create a base view, and an instance view. -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. - -``urls.py`` - -.. include:: ../../examples/blogpost/urls.py - :literal: diff --git a/docs/examples/modelviews.rst b/docs/examples/modelviews.rst deleted file mode 100644 index b67d50d9..00000000 --- a/docs/examples/modelviews.rst +++ /dev/null @@ -1,56 +0,0 @@ -Getting Started - Model Views ------------------------------ - -.. note:: - - A live sandbox instance of this API is available: - - http://rest.ep.io/model-resource-example/ - - You can browse the API using a web browser, or from the command line:: - - curl -X GET http://rest.ep.io/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 <http://docs.djangoproject.com/en/dev/topics/forms/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, first we need to create a Resource for the model. - -``resources.py`` - -.. include:: ../../examples/modelresourceexample/resources.py - :literal: - -Then we simply map a couple of views to the Resource 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://rest.ep.io/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://rest.ep.io/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://rest.ep.io/model-resource-example/ - {"detail": {"bar": ["This field is required."], "baz": ["This field is required."]}} diff --git a/docs/examples/objectstore.rst b/docs/examples/objectstore.rst deleted file mode 100644 index 0939fe9c..00000000 --- a/docs/examples/objectstore.rst +++ /dev/null @@ -1,17 +0,0 @@ -Object Store API -================ - -* http://rest.ep.io/object-store/ - -This example shows an object store API that can be used to store arbitrary serializable content. - -``urls.py`` - -.. include:: ../../examples/objectstore/urls.py - :literal: - -``views.py`` - -.. include:: ../../examples/objectstore/views.py - :literal: - diff --git a/docs/examples/permissions.rst b/docs/examples/permissions.rst deleted file mode 100644 index eafc3255..00000000 --- a/docs/examples/permissions.rst +++ /dev/null @@ -1,66 +0,0 @@ -Permissions -=========== - -This example will show how you can protect your api by using authentication -and how you can limit the amount of requests a user can do to a resource by setting -a throttle to your view. - -Authentication --------------- - -If you want to protect your api from unauthorized users, Django REST Framework -offers you two default authentication methods: - - * Basic Authentication - * Django's session-based authentication - -These authentication methods are by default enabled. But they are not used unless -you specifically state that your view requires authentication. - -To do this you just need to import the `Isauthenticated` class from the frameworks' `permissions` module.:: - - from djangorestframework.permissions import IsAuthenticated - -Then you enable authentication by setting the right 'permission requirement' to the `permissions` class attribute of your View like -the example View below.: - - -.. literalinclude:: ../../examples/permissionsexample/views.py - :pyobject: LoggedInExampleView - -The `IsAuthenticated` permission will only let a user do a 'GET' if he is authenticated. Try it -yourself on the live sandbox__ - -__ http://rest.ep.io/permissions-example/loggedin - - -Throttling ----------- - -If you want to limit the amount of requests a client is allowed to do on -a resource, then you can set a 'throttle' to achieve this. - -For this to work you'll need to import the `PerUserThrottling` class from the `permissions` -module.:: - - from djangorestframework.permissions import PerUserThrottling - -In the example below we have limited the amount of requests one 'client' or 'user' -may do on our view to 10 requests per minute.: - -.. literalinclude:: ../../examples/permissionsexample/views.py - :pyobject: ThrottlingExampleView - -Try it yourself on the live sandbox__. - -__ http://rest.ep.io/permissions-example/throttling - -Now if you want a view to require both aurhentication and throttling, you simply declare them -both:: - - permissions = (PerUserThrottling, Isauthenticated) - -To see what other throttles are available, have a look at the :mod:`permissions` module. - -If you want to implement your own authentication method, then refer to the :mod:`authentication` -module. diff --git a/docs/examples/pygments.rst b/docs/examples/pygments.rst deleted file mode 100644 index 4e72f754..00000000 --- a/docs/examples/pygments.rst +++ /dev/null @@ -1,89 +0,0 @@ -Code Highlighting API -===================== - -This example demonstrates creating a REST API using a :class:`.Resource` with some form validation on the input. -We're going to provide a simple wrapper around the awesome `pygments <http://pygments.org/>`_ library, to create the Web API for a simple pastebin. - -.. note:: - - A live sandbox instance of this API is available at http://rest.ep.io/pygments/ - - You can browse the API using a web browser, or from the command line:: - - curl -X GET http://rest.ep.io/pygments/ -H 'Accept: text/plain' - - -URL configuration ------------------ - -We'll need two resources: - -* A resource which represents the root of the API. -* A resource which represents an instance of a highlighted snippet. - -``urls.py`` - -.. include:: ../../examples/pygments_api/urls.py - :literal: - -Form validation ---------------- - -We'll now add a form to specify what input fields are required when creating a new highlighted code snippet. This will include: - -* The code text itself. -* An optional title for the code. -* A flag to determine if line numbers should be included. -* Which programming language to interpret the code snippet as. -* Which output style to use for the highlighting. - -``forms.py`` - -.. include:: ../../examples/pygments_api/forms.py - :literal: - -Creating the resources ----------------------- - -We'll need to define 3 resource handling methods on our resources. - -* ``PygmentsRoot.get()`` method, which lists all the existing snippets. -* ``PygmentsRoot.post()`` method, which creates new snippets. -* ``PygmentsInstance.get()`` method, which returns existing snippets. - -And set a number of attributes on our resources. - -* Set the ``allowed_methods`` and ``anon_allowed_methods`` attributes on both resources allowing for full unauthenticated access. -* Set the ``form`` attribute on the ``PygmentsRoot`` resource, to give us input validation when we create snippets. -* Set the ``emitters`` attribute on the ``PygmentsInstance`` resource, so that - -``views.py`` - -.. include:: ../../examples/pygments_api/views.py - :literal: - -Completed ---------- - -And we're done. We now have an API that is: - -* **Browseable.** The API supports media types for both programmatic and human access, and can be accessed either via a browser or from the command line. -* **Self describing.** The API serves as it's own documentation. -* **Well connected.** The API can be accessed fully by traversal from the initial URL. Clients never need to construct URLs themselves. - -Our API also supports multiple media types for both input and output, and applies sensible input validation in all cases. - -For example if we make a POST request using form input: - -.. code-block:: bash - - bash: curl -X POST --data 'code=print "hello, world!"' --data 'style=foobar' -H 'X-Requested-With: XMLHttpRequest' http://rest.ep.io/pygments/ - {"detail": {"style": ["Select a valid choice. foobar is not one of the available choices."], "lexer": ["This field is required."]}} - -Or if we make the same request using JSON: - -.. code-block:: bash - - bash: curl -X POST --data-binary '{"code":"print \"hello, world!\"", "style":"foobar"}' -H 'Content-Type: application/json' -H 'X-Requested-With: XMLHttpRequest' http://rest.ep.io/pygments/ - {"detail": {"style": ["Select a valid choice. foobar is not one of the available choices."], "lexer": ["This field is required."]}} - diff --git a/docs/examples/sandbox.rst b/docs/examples/sandbox.rst deleted file mode 100644 index ec465aaf..00000000 --- a/docs/examples/sandbox.rst +++ /dev/null @@ -1,12 +0,0 @@ -Sandbox Root API -================ - -The Resource ------------- - -The root level resource of the Django REST framework examples is a simple read only resource: - -``view.py`` - -.. include:: ../../examples/sandbox/views.py - :literal: diff --git a/docs/examples/views.rst b/docs/examples/views.rst deleted file mode 100644 index db0db0d7..00000000 --- a/docs/examples/views.rst +++ /dev/null @@ -1,56 +0,0 @@ -Getting Started - Views ------------------------ - -.. note:: - - A live sandbox instance of this API is available: - - http://rest.ep.io/resource-example/ - - You can browse the API using a web browser, or from the command line:: - - curl -X GET http://rest.ep.io/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://rest.ep.io/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://rest.ep.io/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://rest.ep.io/resource-example/1/ - {"detail": {"bar": ["This field is required."], "baz": ["This field is required."]}} |