mirror of
https://github.com/encode/django-rest-framework.git
synced 2024-12-04 07:24:03 +03:00
223 lines
14 KiB
HTML
223 lines
14 KiB
HTML
<!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>
|
|
<link href="http://tomchristie.github.com/django-rest-framework/img/favicon.ico" rel="icon" type="image/x-icon">
|
|
<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="migration-page">
|
|
|
|
<div class="wrapper">
|
|
|
|
<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/quickstart">Quickstart</a></li>
|
|
<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/fields">Serializer fields</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/pagination">Pagination</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/browser-enhancements">Browser enhancements</a></li>
|
|
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/browsable-api">The Browsable API</a></li>
|
|
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/rest-hypermedia-hateoas">REST, Hypermedia & HATEOAS</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/migration">2.0 Migration Guide</a></li>
|
|
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/release-notes">Release Notes</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">
|
|
<!-- TODO
|
|
<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="body-content">
|
|
<div class="container-fluid">
|
|
<div class="row-fluid">
|
|
|
|
<div class="span3">
|
|
<!-- TODO
|
|
<p style="margin-top: -12px">
|
|
<a class="btn btn-mini btn-primary" style="width: 60px">« previous</a>
|
|
<a class="btn btn-mini btn-primary" style="float: right; margin-right: 8px; width: 60px;">next »</a>
|
|
</p>
|
|
-->
|
|
<div id="table-of-contents">
|
|
<ul class="nav nav-list side-nav well sidebar-nav-fixed">
|
|
<li class="main"><a href="#20-migration-guide">2.0 Migration Guide</a></li>
|
|
<li><a href="#example-blog-posts-api">Example: Blog Posts API</a></li>
|
|
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
|
|
<div id="main-content" class="span9">
|
|
<h1 id="20-migration-guide">2.0 Migration Guide</h1>
|
|
<blockquote>
|
|
<p>Move fast and break things</p>
|
|
<p>— Mark Zuckerberg, <a href="http://www.wired.com/business/2012/02/zuck-letter/">the Hacker Way</a>.</p>
|
|
</blockquote>
|
|
<p>REST framework 2.0 introduces a radical redesign of the core components, and a large number of backwards breaking changes.</p>
|
|
<h3 id="serialization-redesign">Serialization redesign.</h3>
|
|
<p>REST framework's serialization and deserialization previously used a slightly odd combination of serializers for output, and Django Forms and Model Forms for input. The serialization core has been completely redesigned based on work that was originally intended for Django core.</p>
|
|
<p>2.0's form-like serializers comprehensively address those issues, and are a much more flexible and clean solution to the problems around accepting both form-based and non-form based inputs.</p>
|
|
<h3 id="generic-views-improved">Generic views improved.</h3>
|
|
<p>When REST framework 0.1 was released the current Django version was 1.2. REST framework included a backport of the Django 1.3's upcoming <code>View</code> class, but it didn't take full advantage of the generic view implementations.</p>
|
|
<p>As of 2.0 the generic views in REST framework tie in much more cleanly and obviously with Django's existing codebase, and the mixin architecture is radically simplified.</p>
|
|
<h3 id="cleaner-request-response-cycle">Cleaner request-response cycle.</h3>
|
|
<p>REST framework 2.0's request-response cycle is now much less complex.</p>
|
|
<ul>
|
|
<li>Responses inherit from <code>SimpleTemplateResponse</code>, allowing rendering to be delegated to the response, not handled by the view.</li>
|
|
<li>Requests extend the regular <code>HttpRequest</code>, allowing authentication and parsing to be delegated to the request, not handled by the view.</li>
|
|
</ul>
|
|
<h3 id="renamed-attributes-classes">Renamed attributes & classes.</h3>
|
|
<p>Various attributes and classes have been renamed in order to fit in better with Django's conventions.</p>
|
|
<h2 id="example-blog-posts-api">Example: Blog Posts API</h2>
|
|
<p>Let's take a look at an example from the REST framework 0.4 documentation...</p>
|
|
<pre class="prettyprint lang-py"><code>from djangorestframework.resources import ModelResource
|
|
from djangorestframework.reverse import reverse
|
|
from blogpost.models import BlogPost, Comment
|
|
|
|
class BlogPostResource(ModelResource):
|
|
"""
|
|
A Blog Post has a *title* and *content*, and can be associated
|
|
with zero or more comments.
|
|
"""
|
|
model = BlogPost
|
|
fields = ('created', 'title', 'slug', 'content', 'url', 'comments')
|
|
ordering = ('-created',)
|
|
|
|
def url(self, instance):
|
|
return reverse('blog-post',
|
|
kwargs={'key': instance.key},
|
|
request=self.request)
|
|
|
|
def comments(self, instance):
|
|
return reverse('comments',
|
|
kwargs={'blogpost': instance.key},
|
|
request=self.request)
|
|
|
|
class CommentResource(ModelResource):
|
|
"""
|
|
A Comment is associated with a given Blog Post and has a
|
|
*username* and *comment*, and optionally a *rating*.
|
|
"""
|
|
model = Comment
|
|
fields = ('username', 'comment', 'created', 'rating', 'url', 'blogpost')
|
|
ordering = ('-created',)
|
|
|
|
def blogpost(self, instance):
|
|
return reverse('blog-post',
|
|
kwargs={'key': instance.blogpost.key},
|
|
request=self.request)
|
|
</code></pre>
|
|
<p>There's a bit of a mix of concerns going on there. We've got some information about how the data should be serialized, such as the <code>fields</code> attribute, and some information about how it should be retrieved from the database - the <code>ordering</code> attribute.</p>
|
|
<p>Let's start to re-write this for REST framework 2.0.</p>
|
|
<pre class="prettyprint lang-py"><code>from rest_framework import serializers
|
|
|
|
class BlogPostSerializer(serializers.HyperlinkedModelSerializer):
|
|
model = BlogPost
|
|
fields = ('created', 'title', 'slug', 'content', 'url', 'comments')
|
|
|
|
class CommentSerializer(serializers.HyperlinkedModelSerializer):
|
|
model = Comment
|
|
fields = ('username', 'comment', 'created', 'rating', 'url', 'blogpost')
|
|
</code></pre>
|
|
</div><!--/span-->
|
|
</div><!--/row-->
|
|
</div><!--/.fluid-container-->
|
|
</div><!--/.body content-->
|
|
|
|
<div id="push"></div>
|
|
</div><!--/.wrapper -->
|
|
|
|
<footer class="span12">
|
|
<p>Sponsored by <a href="http://dabapps.com/">DabApps</a>.</a></p>
|
|
</footer>
|
|
|
|
<!-- 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-1.0.js"></script>
|
|
<script src="http://tomchristie.github.com/django-rest-framework/js/bootstrap-2.1.1-min.js"></script>
|
|
<script>
|
|
//$('.side-nav').scrollspy()
|
|
var shiftWindow = function() { scrollBy(0, -50) };
|
|
if (location.hash) shiftWindow();
|
|
window.addEventListener("hashchange", shiftWindow);
|
|
|
|
$('.dropdown-menu').on('click touchstart', function(event) {
|
|
event.stopPropagation();
|
|
});
|
|
</script>
|
|
</body></html>
|