From d6d22675856b609465181d5b82db253c33a9af47 Mon Sep 17 00:00:00 2001
From: Tom Christie <tom@tomchristie.com>
Date: Fri, 14 Sep 2012 12:44:04 +0100
Subject: [PATCH] Flesh out Resources/Routers tutorial a little

---
 api-guide/throttling.html                    |   4 +-
 topics/changelog.html                        | 249 +++++++++++++++++++
 tutorial/6-resource-orientated-projects.html |  37 ++-
 3 files changed, 281 insertions(+), 9 deletions(-)
 create mode 100644 topics/changelog.html
diff --git a/api-guide/throttling.html b/api-guide/throttling.html
index 7262dff1e..71be281a6 100644
--- a/api-guide/throttling.html
+++ b/api-guide/throttling.html
@@ -162,7 +162,7 @@ def example_view(request, format=None):
 </ul>
 <p><code>AnonThrottle</code> is suitable if you want to restrict the rate of requests from unknown sources.</p>
 <h2 id="userratethrottle">UserRateThrottle</h2>
-<p>The <code>UserThrottle</code> will throttle users to a given rate of requests across the API.  The user id is used to generate a unique key to throttle against.  Unauthenticted requests will fall back to using the IP address of the incoming request is used to generate a unique key to throttle against.</p>
+<p>The <code>UserThrottle</code> will throttle users to a given rate of requests across the API.  The user id is used to generate a unique key to throttle against.  Unauthenticted requests will fall back to using the IP address of the incoming request to generate a unique key to throttle against.</p>
 <p>The allowed request rate is determined from one of the following (in order of preference).</p>
 <ul>
 <li>The <code>rate</code> property on the class, which may be provided by overriding <code>UserThrottle</code> and setting the property.</li>
@@ -188,7 +188,7 @@ class SustainedRateThrottle(UserRateThrottle):
     }
 }
 </code></pre>
-<p><code>UserThrottle</code> is suitable if you want a simple global rate restriction per-user.</p>
+<p><code>UserThrottle</code> is suitable if you want simple global rate restrictions per-user.</p>
 <h2 id="scopedratethrottle">ScopedRateThrottle</h2>
 <p>The <code>ScopedThrottle</code> class can be used to restrict access to specific parts of the API.  This throttle will only be applied if the view that is being accessed includes a <code>.throttle_scope</code> property.  The unique throttle key will then be formed by concatenating the "scope" of the request with the unqiue user id or IP address.</p>
 <p>The allowed request rate is determined by the <code>DEFAULT_THROTTLE_RATES</code> setting using a key from the request "scope".</p>
diff --git a/topics/changelog.html b/topics/changelog.html
new file mode 100644
index 000000000..4a7e9e58c
--- /dev/null
+++ b/topics/changelog.html
@@ -0,0 +1,249 @@
+<!DOCTYPE html>
+<html lang="en"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+    <meta charset="utf-8">
+    <title>Django REST framework</title>
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <meta name="description" content="">
+    <meta name="author" content="">
+
+    <!-- Le styles -->
+    <link href="http://tomchristie.github.com/django-rest-framework/css/prettify.css" rel="stylesheet">
+    <link href="http://tomchristie.github.com/django-rest-framework/css/bootstrap.css" rel="stylesheet">
+    <link href="http://tomchristie.github.com/django-rest-framework/css/bootstrap-responsive.css" rel="stylesheet">
+    <link href="http://tomchristie.github.com/django-rest-framework/css/default.css" rel="stylesheet">
+
+    <!-- Le HTML5 shim, for IE6-8 support of HTML5 elements -->
+    <!--[if lt IE 9]>
+      <script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
+    <![endif]-->
+  <body onload="prettyPrint()" class="changelog">
+
+    <div class="navbar navbar-inverse navbar-fixed-top">
+      <div class="navbar-inner">
+        <div class="container-fluid">
+            <a class="repo-link btn btn-primary btn-small" href="https://github.com/tomchristie/django-rest-framework/tree/restframework2">GitHub</a>
+          <a class="btn btn-navbar" data-toggle="collapse" data-target=".nav-collapse">
+            <span class="icon-bar"></span>
+            <span class="icon-bar"></span>
+            <span class="icon-bar"></span>
+          </a>
+          <a class="brand" href="http://tomchristie.github.com/django-rest-framework">Django REST framework</a>
+          <div class="nav-collapse collapse">
+            <ul class="nav">
+              <li><a href="http://tomchristie.github.com/django-rest-framework">Home</a></li>
+              <li class="dropdown">
+                <a href="#" class="dropdown-toggle" data-toggle="dropdown">Tutorial <b class="caret"></b></a>
+                <ul class="dropdown-menu">
+                  <li><a href="http://tomchristie.github.com/django-rest-framework/tutorial/1-serialization">1 - Serialization</a></li>
+                  <li><a href="http://tomchristie.github.com/django-rest-framework/tutorial/2-requests-and-responses">2 - Requests and responses</a></li>
+                  <li><a href="http://tomchristie.github.com/django-rest-framework/tutorial/3-class-based-views">3 - Class based views</a></li>
+                  <li><a href="http://tomchristie.github.com/django-rest-framework/tutorial/4-authentication-permissions-and-throttling">4 - Authentication, permissions and throttling</a></li>
+                  <li><a href="http://tomchristie.github.com/django-rest-framework/tutorial/5-relationships-and-hyperlinked-apis">5 - Relationships and hyperlinked APIs</a></li>
+                  <li><a href="http://tomchristie.github.com/django-rest-framework/tutorial/6-resource-orientated-projects">6 - Resource orientated projects</a></li>
+                </ul>
+              </li>
+              <li class="dropdown">
+                <a href="#" class="dropdown-toggle" data-toggle="dropdown">API Guide <b class="caret"></b></a>
+                <ul class="dropdown-menu">
+                  <li><a href="http://tomchristie.github.com/django-rest-framework/api-guide/requests">Requests</a></li>
+                  <li><a href="http://tomchristie.github.com/django-rest-framework/api-guide/responses">Responses</a></li>
+                  <li><a href="http://tomchristie.github.com/django-rest-framework/api-guide/views">Views</a></li>
+                  <li><a href="http://tomchristie.github.com/django-rest-framework/api-guide/generic-views">Generic views</a></li>
+                  <li><a href="http://tomchristie.github.com/django-rest-framework/api-guide/parsers">Parsers</a></li>
+                  <li><a href="http://tomchristie.github.com/django-rest-framework/api-guide/renderers">Renderers</a></li>
+                  <li><a href="http://tomchristie.github.com/django-rest-framework/api-guide/serializers">Serializers</a></li>
+                  <li><a href="http://tomchristie.github.com/django-rest-framework/api-guide/authentication">Authentication</a></li>
+                  <li><a href="http://tomchristie.github.com/django-rest-framework/api-guide/permissions">Permissions</a></li>
+                  <li><a href="http://tomchristie.github.com/django-rest-framework/api-guide/throttling">Throttling</a></li>
+                  <li><a href="http://tomchristie.github.com/django-rest-framework/api-guide/content-negotiation">Content negotiation</a></li>
+                  <li><a href="http://tomchristie.github.com/django-rest-framework/api-guide/format-suffixes">Format suffixes</a></li>
+                  <li><a href="http://tomchristie.github.com/django-rest-framework/api-guide/reverse">Returning URLs</a></li>
+                  <li><a href="http://tomchristie.github.com/django-rest-framework/api-guide/exceptions">Exceptions</a></li>
+                  <li><a href="http://tomchristie.github.com/django-rest-framework/api-guide/status-codes">Status codes</a></li>
+                  <li><a href="http://tomchristie.github.com/django-rest-framework/api-guide/settings">Settings</a></li>
+                </ul>
+              </li>
+              <li class="dropdown">
+                <a href="#" class="dropdown-toggle" data-toggle="dropdown">Topics <b class="caret"></b></a>
+                <ul class="dropdown-menu">
+                  <li><a href="http://tomchristie.github.com/django-rest-framework/topics/csrf">Working with AJAX and CSRF</a></li>
+                  <li><a href="http://tomchristie.github.com/django-rest-framework/topics/formoverloading">Browser based PUT, PATCH and DELETE</a></li>
+                  <li><a href="http://tomchristie.github.com/django-rest-framework/topics/contributing">Contributing to REST framework</a></li>
+                  <li><a href="http://tomchristie.github.com/django-rest-framework/topics/credits">Credits</a></li>
+                </ul>
+              </li>
+            </ul>
+            <ul class="nav pull-right">
+              <li class="dropdown">
+                <a href="#" class="dropdown-toggle" data-toggle="dropdown">Version: 2.0.0 <b class="caret"></b></a>
+                <ul class="dropdown-menu">
+                  <li><a href="#">Trunk</a></li>
+                  <li><a href="#">2.0.0</a></li>
+                </ul>
+              </li>
+            </ul>
+          </div><!--/.nav-collapse -->
+        </div>
+      </div>
+    </div>
+
+    <div class="container-fluid">
+      <div class="row-fluid">
+        <div class="span3">
+          <div id="table-of-contents" class="well affix span3">
+            <ul class="nav nav-list side-nav">
+              <li><a href="#200">2.0.0</a></li>
+<li><a href="#040">0.4.0</a></li>
+<li><a href="#033">0.3.3</a></li>
+<li><a href="#032">0.3.2</a></li>
+<li><a href="#031">0.3.1</a></li>
+<li><a href="#030">0.3.0</a></li>
+<li><a href="#024">0.2.4</a></li>
+<li><a href="#023">0.2.3</a></li>
+<li><a href="#022">0.2.2</a></li>
+<li><a href="#021">0.2.1</a></li>
+<li><a href="#020">0.2.0</a></li>
+<li><a href="#011">0.1.1</a></li>
+<li><a href="#010">0.1.0</a></li>
+
+            </ul>
+          </div>
+        </div>
+
+        <div id="main-content" class="span9">
+          <h1 id="release-notes">Release Notes</h1>
+<h2 id="200">2.0.0</h2>
+<p><strong>TODO:</strong> Explain REST framework 2.0</p>
+<h2 id="040">0.4.0</h2>
+<ul>
+<li>Supports Django 1.5.</li>
+<li>Fixes issues with 'HEAD' method.</li>
+<li>Allow views to specify template used by TemplateRenderer</li>
+<li>More consistent error responses</li>
+<li>Some serializer fixes</li>
+<li>Fix internet explorer ajax behaviour</li>
+<li>Minor xml and yaml fixes</li>
+<li>Improve setup (eg use staticfiles, not the defunct ADMIN_MEDIA_PREFIX)</li>
+<li>Sensible absolute URL generation, not using hacky set_script_prefix</li>
+</ul>
+<h2 id="033">0.3.3</h2>
+<ul>
+<li>Added DjangoModelPermissions class to support <code>django.contrib.auth</code> style permissions.</li>
+<li>Use <code>staticfiles</code> for css files.</li>
+<li>Easier to override.  Won't conflict with customised admin styles (eg grappelli)</li>
+<li>Templates are now nicely namespaced.</li>
+<li>Allows easier overriding.</li>
+<li>Drop implied 'pk' filter if last arg in urlconf is unnamed.</li>
+<li>Too magical.  Explict is better than implicit.</li>
+<li>Saner template variable autoescaping.</li>
+<li>Tider setup.py</li>
+<li>Updated for URLObject 2.0</li>
+<li>Bugfixes:</li>
+<li>Bug with PerUserThrottling when user contains unicode chars.</li>
+</ul>
+<h2 id="032">0.3.2</h2>
+<ul>
+<li>Bugfixes:</li>
+<li>Fix 403 for POST and PUT from the UI with UserLoggedInAuthentication (#115)</li>
+<li>serialize_model method in serializer.py may cause wrong value (#73)</li>
+<li>Fix Error when clicking OPTIONS button (#146)</li>
+<li>And many other fixes</li>
+<li>Remove short status codes</li>
+<li>Zen of Python: "There should be one-- and preferably only one --obvious way to do it."</li>
+<li>get_name, get_description become methods on the view - makes them overridable.</li>
+<li>Improved model mixin API - Hooks for build_query, get_instance_data, get_model, get_queryset, get_ordering</li>
+</ul>
+<h2 id="031">0.3.1</h2>
+<ul>
+<li>[not documented]</li>
+</ul>
+<h2 id="030">0.3.0</h2>
+<ul>
+<li>JSONP Support</li>
+<li>Bugfixes, including support for latest markdown release</li>
+</ul>
+<h2 id="024">0.2.4</h2>
+<ul>
+<li>Fix broken IsAdminUser permission.</li>
+<li>OPTIONS support.</li>
+<li>XMLParser.</li>
+<li>Drop mentions of Blog, BitBucket.</li>
+</ul>
+<h2 id="023">0.2.3</h2>
+<ul>
+<li>Fix some throttling bugs.</li>
+<li><code>X-Throttle</code> header on throttling.</li>
+<li>Support for nesting resources on related models.</li>
+</ul>
+<h2 id="022">0.2.2</h2>
+<ul>
+<li>Throttling support complete.</li>
+</ul>
+<h2 id="021">0.2.1</h2>
+<ul>
+<li>Couple of simple bugfixes over 0.2.0</li>
+</ul>
+<h2 id="020">0.2.0</h2>
+<ul>
+<li>
+<p>Big refactoring changes since 0.1.0, ask on the discussion group if anything isn't clear.
+  The public API has been massively cleaned up.  Expect it to be fairly stable from here on in.</p>
+</li>
+<li>
+<p><code>Resource</code> becomes decoupled into <code>View</code> and <code>Resource</code>, your views should now inherit from <code>View</code>, not <code>Resource</code>.</p>
+</li>
+<li>
+<p>The handler functions on views <code>.get() .put() .post()</code> etc, no longer have the <code>content</code> and <code>auth</code> args.
+  Use <code>self.CONTENT</code> inside a view to access the deserialized, validated content.
+  Use <code>self.user</code> inside a view to access the authenticated user.</p>
+</li>
+<li>
+<p><code>allowed_methods</code> and <code>anon_allowed_methods</code> are now defunct.  if a method is defined, it's available.
+  The <code>permissions</code> attribute on a <code>View</code> is now used to provide generic permissions checking.
+  Use permission classes such as <code>FullAnonAccess</code>, <code>IsAuthenticated</code> or <code>IsUserOrIsAnonReadOnly</code> to set the permissions.</p>
+</li>
+<li>
+<p>The <code>authenticators</code> class becomes <code>authentication</code>.  Class names change to <code>Authentication</code>.</p>
+</li>
+<li>
+<p>The <code>emitters</code> class becomes <code>renderers</code>.  Class names change to <code>Renderers</code>.</p>
+</li>
+<li>
+<p><code>ResponseException</code> becomes <code>ErrorResponse</code>.</p>
+</li>
+<li>
+<p>The mixin classes have been nicely refactored, the basic mixins are now <code>RequestMixin</code>, <code>ResponseMixin</code>, <code>AuthMixin</code>, and <code>ResourceMixin</code>
+  You can reuse these mixin classes individually without using the <code>View</code> class.</p>
+</li>
+</ul>
+<h2 id="011">0.1.1</h2>
+<ul>
+<li>Final build before pulling in all the refactoring changes for 0.2, in case anyone needs to hang on to 0.1.</li>
+</ul>
+<h2 id="010">0.1.0</h2>
+<ul>
+<li>Initial release.</li>
+</ul>
+        </div><!--/span-->
+      </div><!--/row-->
+    </div><!--/.fluid-container-->
+
+    <!-- Le javascript
+    ================================================== -->
+    <!-- Placed at the end of the document so the pages load faster -->
+    <script src="http://tomchristie.github.com/django-rest-framework/js/jquery-1.8.1-min.js"></script>
+    <script src="http://tomchristie.github.com/django-rest-framework/js/prettify.js"></script>
+    <script src="http://tomchristie.github.com/django-rest-framework/js/bootstrap-dropdown.js"></script>
+    <script src="http://tomchristie.github.com/django-rest-framework/js/bootstrap-scrollspy.js"></script>
+    <script src="http://tomchristie.github.com/django-rest-framework/js/bootstrap-collapse.js"></script>
+    <script>
+      //$('.side-nav').scrollspy()
+      var shiftWindow = function() { scrollBy(0, -50) };
+      if (location.hash) shiftWindow();
+      window.addEventListener("hashchange", shiftWindow);
+
+      $('.dropdown-menu').click(function(event) {
+        event.stopPropagation();
+      });
+    </script>
+</body></html>
\ No newline at end of file
diff --git a/tutorial/6-resource-orientated-projects.html b/tutorial/6-resource-orientated-projects.html
index 44df67807..ebb225058 100644
--- a/tutorial/6-resource-orientated-projects.html
+++ b/tutorial/6-resource-orientated-projects.html
@@ -92,7 +92,8 @@
         <div class="span3">
           <div id="table-of-contents" class="well affix span3">
             <ul class="nav nav-list side-nav">
-              <li><a href="#trade-offs-between-views-vs-resources">Trade-offs between views vs resources.</a></li>
+              <li><a href="#using-routers">Using Routers</a></li>
+<li><a href="#trade-offs-between-views-vs-resources">Trade-offs between views vs resources.</a></li>
 <li><a href="#onwards-and-upwards">Onwards and upwards.</a></li>
 
             </ul>
@@ -100,7 +101,9 @@
         </div>
 
         <div id="main-content" class="span9">
-          <p>serializers.py</p>
+          <p>In REST framework Resources classes are just View classes that don't have any handler methods bound to them.  This allows us to seperate out the behaviour of the classes from how that behaviour should be bound to a set of URLs.</p>
+<p>For instance, given our serializers</p>
+<p>serializers.py</p>
 <pre class="prettyprint lang-py"><code>class BlogPostSerializer(URLModelSerializer):
     class Meta:
         model = BlogPost
@@ -109,20 +112,40 @@ class CommentSerializer(URLModelSerializer):
     class Meta:
         model = Comment
 </code></pre>
+<p>We can re-write our 4 sets of views into something more compact...</p>
 <p>resources.py</p>
 <pre class="prettyprint lang-py"><code>class BlogPostResource(ModelResource):
     serializer_class = BlogPostSerializer
     model = BlogPost
-    permissions = [AdminOrAnonReadonly()]
-    throttles = [AnonThrottle(rate='5/min')]
+    permissions_classes = (permissions.IsAuthenticatedOrReadOnly,)
+    throttle_classes = (throttles.UserRateThrottle,)
 
 class CommentResource(ModelResource):
     serializer_class = CommentSerializer
     model = Comment
-    permissions = [AdminOrAnonReadonly()]
-    throttles = [AnonThrottle(rate='5/min')]
+    permissions_classes = (permissions.IsAuthenticatedOrReadOnly,)
+    throttle_classes = (throttles.UserRateThrottle,)
 </code></pre>
-<p>Now that we're using Resources rather than Views, we don't need to design the urlconf ourselves.  The conventions for wiring up resources into views and urls are handled automatically.  All we need to do is register the appropriate resources with a router, and let it do the rest.  Here's our re-wired <code>urls.py</code> file.</p>
+<p>The handler methods only get bound to the actions when we define the URLConf. Here's our urls.py:</p>
+<pre class="prettyprint lang-py"><code>comment_root = CommentResource.as_view(actions={
+    'get': 'list',
+    'post': 'create'
+})
+comment_instance = CommentInstance.as_view(actions={
+    'get': 'retrieve',
+    'put': 'update',
+    'delete': 'destroy'
+})
+... # And for blog post
+
+urlpatterns = patterns('blogpost.views',
+    url(r'^$', comment_root),
+    url(r'^(?P&lt;pk&gt;[0-9]+)$', comment_instance)
+    ...  # And for blog post  
+)
+</code></pre>
+<h2 id="using-routers">Using Routers</h2>
+<p>Right now that hasn't really saved us a lot of code.  However, now that we're using Resources rather than Views, we actually don't need to design the urlconf ourselves.  The conventions for wiring up resources into views and urls can be handled automatically, using <code>Router</code> classes.  All we need to do is register the appropriate resources with a router, and let it do the rest.  Here's our re-wired <code>urls.py</code> file.</p>
 <pre class="prettyprint lang-py"><code>from blog import resources
 from djangorestframework.routers import DefaultRouter
 
