From 9871532746aee7e0f5796ae24cfb44c878759c38 Mon Sep 17 00:00:00 2001
From: Marko Tibold <marko@tibold.nl>
Date: Mon, 2 Jan 2012 18:12:22 +0100
Subject: [PATCH] Added an example of how to use authentication and throttling.

---
 docs/examples/permissions.rst | 66 +++++++++++++++++++++++++++++++++++
 1 file changed, 66 insertions(+)
 create mode 100644 docs/examples/permissions.rst

diff --git a/docs/examples/permissions.rst b/docs/examples/permissions.rst
new file mode 100644
index 000000000..cfd7b4461
--- /dev/null
+++ b/docs/examples/permissions.rst
@@ -0,0 +1,66 @@
+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 :doc:`../library/permissions` module.
+
+If you want to implement your own authentication method, then refer to the :doc:`../library/authentication` 
+module.