encode/django-rest-framework
1
1
Fork 0
mirror of https://github.com/encode/django-rest-framework.git synced 2024-12-04 23:44:07 +03:00
Code Issues Packages Projects Releases Wiki Activity

Flesh out Resources/Routers tutorial a little

Browse Source
This commit is contained in:
Tom Christie 2012-09-14 12:44:04 +01:00
parent ac8760b22f
commit d6d2267585
3 changed files with 281 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
api-guide/throttling.html
View File

@ -162,7 +162,7 @@ def example_view(request, format=None):
</ul> </ul>
<p><code>AnonThrottle</code> is suitable if you want to restrict the rate of requests from unknown sources.</p> <p><code>AnonThrottle</code> is suitable if you want to restrict the rate of requests from unknown sources.</p>
<h2 id="userratethrottle">UserRateThrottle</h2> <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> <p>The allowed request rate is determined from one of the following (in order of preference).</p>
<ul> <ul>
<li>The <code>rate</code> property on the class, which may be provided by overriding <code>UserThrottle</code> and setting the property.</li> <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> </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> <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 <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> <p>The allowed request rate is determined by the <code>DEFAULT_THROTTLE_RATES</code> setting using a key from the request "scope".</p>

249
topics/changelog.html Normal file
View File

@ -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>

37
tutorial/6-resource-orientated-projects.html
View File

@ -92,7 +92,8 @@
<div class="span3"> <div class="span3">
<div id="table-of-contents" class="well affix span3"> <div id="table-of-contents" class="well affix span3">
<ul class="nav nav-list side-nav"> <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> <li><a href="#onwards-and-upwards">Onwards and upwards.</a></li>
</ul> </ul>
@ -100,7 +101,9 @@
</div> </div>
<div id="main-content" class="span9"> <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): <pre class="prettyprint lang-py"><code>class BlogPostSerializer(URLModelSerializer):
class Meta: class Meta:
model = BlogPost model = BlogPost
@ -109,20 +112,40 @@ class CommentSerializer(URLModelSerializer):
class Meta: class Meta:
model = Comment model = Comment
</code></pre> </code></pre>
<p>We can re-write our 4 sets of views into something more compact...</p>
<p>resources.py</p> <p>resources.py</p>
<pre class="prettyprint lang-py"><code>class BlogPostResource(ModelResource): <pre class="prettyprint lang-py"><code>class BlogPostResource(ModelResource):
serializer_class = BlogPostSerializer serializer_class = BlogPostSerializer
model = BlogPost model = BlogPost
permissions = [AdminOrAnonReadonly()] permissions_classes = (permissions.IsAuthenticatedOrReadOnly,)
throttles = [AnonThrottle(rate='5/min')] throttle_classes = (throttles.UserRateThrottle,)
class CommentResource(ModelResource): class CommentResource(ModelResource):
serializer_class = CommentSerializer serializer_class = CommentSerializer
model = Comment model = Comment
permissions = [AdminOrAnonReadonly()] permissions_classes = (permissions.IsAuthenticatedOrReadOnly,)
throttles = [AnonThrottle(rate='5/min')] throttle_classes = (throttles.UserRateThrottle,)
</code></pre> </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 <pre class="prettyprint lang-py"><code>from blog import resources
from djangorestframework.routers import DefaultRouter from djangorestframework.routers import DefaultRouter