mirror of
https://github.com/encode/django-rest-framework.git
synced 2024-11-26 11:33:59 +03:00
551 lines
24 KiB
HTML
551 lines
24 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="en">
|
|
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
|
|
<meta charset="utf-8">
|
|
<title>3.2 Announcement - Django REST framework</title>
|
|
<link href="../../img/favicon.ico" rel="icon" type="image/x-icon">
|
|
<link rel="canonical" href="http://www.django-rest-framework.org/topics/3.2-announcement/" />
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
<meta name="description" content="Django, API, REST, 3.2 Announcement">
|
|
<meta name="author" content="Tom Christie">
|
|
|
|
<!-- Le styles -->
|
|
<link href="../../css/prettify.css" rel="stylesheet">
|
|
<link href="../../css/bootstrap.css" rel="stylesheet">
|
|
<link href="../../css/bootstrap-responsive.css" rel="stylesheet">
|
|
<link href="../../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]-->
|
|
|
|
<script type="text/javascript">
|
|
var _gaq = _gaq || [];
|
|
_gaq.push(['_setAccount', 'UA-18852272-2']);
|
|
_gaq.push(['_trackPageview']);
|
|
|
|
(function() {
|
|
var ga = document.createElement('script');
|
|
ga.type = 'text/javascript';
|
|
ga.async = true;
|
|
ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
|
|
var s = document.getElementsByTagName('script')[0];
|
|
s.parentNode.insertBefore(ga, s);
|
|
})();
|
|
</script>
|
|
|
|
<style>
|
|
#sidebarInclude img {
|
|
margin-bottom: 10px;
|
|
}
|
|
#sidebarInclude a.promo {
|
|
color: black;
|
|
}
|
|
@media (max-width: 767px) {
|
|
div.promo {
|
|
display: none;
|
|
}
|
|
}
|
|
</style>
|
|
</head>
|
|
<body onload="prettyPrint()" class="-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/master">GitHub</a>
|
|
<a class="repo-link btn btn-inverse btn-small " rel="prev" href="../3.3-announcement/">
|
|
Next <i class="icon-arrow-right icon-white"></i>
|
|
</a>
|
|
<a class="repo-link btn btn-inverse btn-small " rel="next" href="../3.1-announcement/">
|
|
<i class="icon-arrow-left icon-white"></i> Previous
|
|
</a>
|
|
<a id="search_modal_show" class="repo-link btn btn-inverse btn-small" href="#mkdocs_search_modal" data-toggle="modal" data-target="#mkdocs_search_modal"><i class="icon-search icon-white"></i> Search</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://www.django-rest-framework.org">Django REST framework</a>
|
|
<div class="nav-collapse collapse">
|
|
|
|
<!-- Main navigation -->
|
|
<ul class="nav navbar-nav">
|
|
|
|
<li >
|
|
<a href="../..">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="../../tutorial/quickstart/">Quickstart</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../tutorial/1-serialization/">1 - Serialization</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../tutorial/2-requests-and-responses/">2 - Requests and responses</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../tutorial/3-class-based-views/">3 - Class based views</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../tutorial/4-authentication-and-permissions/">4 - Authentication and permissions</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../tutorial/5-relationships-and-hyperlinked-apis/">5 - Relationships and hyperlinked APIs</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../tutorial/6-viewsets-and-routers/">6 - Viewsets and routers</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../tutorial/7-schemas-and-client-libraries/">7 - Schemas and client libraries</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="../../api-guide/requests/">Requests</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../api-guide/responses/">Responses</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../api-guide/views/">Views</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../api-guide/generic-views/">Generic views</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../api-guide/viewsets/">Viewsets</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../api-guide/routers/">Routers</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../api-guide/parsers/">Parsers</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../api-guide/renderers/">Renderers</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../api-guide/serializers/">Serializers</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../api-guide/fields/">Serializer fields</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../api-guide/relations/">Serializer relations</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../api-guide/validators/">Validators</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../api-guide/authentication/">Authentication</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../api-guide/permissions/">Permissions</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../api-guide/throttling/">Throttling</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../api-guide/filtering/">Filtering</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../api-guide/pagination/">Pagination</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../api-guide/versioning/">Versioning</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../api-guide/content-negotiation/">Content negotiation</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../api-guide/metadata/">Metadata</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../api-guide/schemas/">Schemas</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../api-guide/format-suffixes/">Format suffixes</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../api-guide/reverse/">Returning URLs</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../api-guide/exceptions/">Exceptions</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../api-guide/status-codes/">Status codes</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../api-guide/testing/">Testing</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../api-guide/settings/">Settings</a>
|
|
</li>
|
|
|
|
</ul>
|
|
</li>
|
|
|
|
<li class="dropdown active">
|
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Topics <b class="caret"></b></a>
|
|
<ul class="dropdown-menu">
|
|
|
|
<li >
|
|
<a href="../documenting-your-api/">Documenting your API</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../api-clients/">API Clients</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../internationalization/">Internationalization</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../ajax-csrf-cors/">AJAX, CSRF & CORS</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../html-and-forms/">HTML & Forms</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../browser-enhancements/">Browser Enhancements</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../browsable-api/">The Browsable API</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../rest-hypermedia-hateoas/">REST, Hypermedia & HATEOAS</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../third-party-packages/">Third Party Packages</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../tutorials-and-resources/">Tutorials and Resources</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../contributing/">Contributing to REST framework</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../project-management/">Project management</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../jobs/">Jobs</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../3.0-announcement/">3.0 Announcement</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../3.1-announcement/">3.1 Announcement</a>
|
|
</li>
|
|
|
|
<li class="active" >
|
|
<a href="./">3.2 Announcement</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../3.3-announcement/">3.3 Announcement</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../3.4-announcement/">3.4 Announcement</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../3.5-announcement/">3.5 Announcement</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../3.6-announcement/">3.6 Announcement</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../kickstarter-announcement/">Kickstarter Announcement</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../mozilla-grant/">Mozilla Grant</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../funding/">Funding</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../release-notes/">Release Notes</a>
|
|
</li>
|
|
|
|
</ul>
|
|
</li>
|
|
|
|
|
|
</ul>
|
|
|
|
</div>
|
|
<!--/.nav-collapse -->
|
|
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="body-content">
|
|
<div class="container-fluid">
|
|
<!-- Search Modal -->
|
|
<div id="mkdocs_search_modal" class="modal hide fade" tabindex="-1" role="dialog" aria-labelledby="myModalLabel" aria-hidden="true">
|
|
<div class="modal-header">
|
|
<button type="button" class="close" data-dismiss="modal" aria-hidden="true">×</button>
|
|
<h3 id="myModalLabel">Documentation search</h3>
|
|
</div>
|
|
|
|
<div class="modal-body">
|
|
<form role="form" autocomplete="off">
|
|
<div class="form-group">
|
|
<input type="text" name="q" class="form-control" placeholder="Search..." id="mkdocs-search-query">
|
|
</div>
|
|
</form>
|
|
<div id="mkdocs-search-results"></div>
|
|
</div>
|
|
|
|
<div class="modal-footer">
|
|
<button class="btn" data-dismiss="modal" aria-hidden="true">Close</button>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="row-fluid">
|
|
<div class="span3">
|
|
<div id="table-of-contents">
|
|
<ul class="nav nav-list side-nav well sidebar-nav-fixed">
|
|
|
|
|
|
|
|
<li class="main">
|
|
<a href="#django-rest-framework-32">Django REST framework 3.2</a>
|
|
</li>
|
|
|
|
|
|
<li>
|
|
<a href="#adminrenderer">AdminRenderer</a>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="#supported-versions">Supported versions</a>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="#deprecations">Deprecations</a>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="#modifications-to-list-behaviors">Modifications to list behaviors</a>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="#whats-next">What's next?</a>
|
|
</li>
|
|
|
|
|
|
|
|
<div class="promo">
|
|
<hr/>
|
|
<div id="sidebarInclude">
|
|
</div>
|
|
</ul>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
<div id="main-content" class="span9">
|
|
|
|
|
|
|
|
<h1 id="django-rest-framework-32"><a class="toclink" href="#django-rest-framework-32">Django REST framework 3.2</a></h1>
|
|
<p>The 3.2 release is the first version to include an admin interface for the browsable API.</p>
|
|
<p><img alt="The AdminRenderer" src="../../img/admin.png" /></p>
|
|
<p>This interface is intended to act as a more user-friendly interface to the API. It can be used either as a replacement to the existing <code>BrowsableAPIRenderer</code>, or used together with it, allowing you to switch between the two styles as required.</p>
|
|
<p>We've also fixed a huge number of issues, and made numerous cleanups and improvements.</p>
|
|
<p>Over the course of the 3.1.x series we've <a href="https://github.com/tomchristie/django-rest-framework/issues?utf8=%E2%9C%93&q=closed%3A%3E2015-03-05">resolved nearly 600 tickets</a> on our GitHub issue tracker. This means we're currently running at a rate of <strong>closing around 100 issues or pull requests per month</strong>.</p>
|
|
<p>None of this would have been possible without the support of our wonderful Kickstarter backers. If you're looking for a job in Django development we'd strongly recommend taking <a href="http://www.django-rest-framework.org/topics/kickstarter-announcement/#sponsors">a look through our sponsors</a> and finding out who's hiring.</p>
|
|
<h2 id="adminrenderer"><a class="toclink" href="#adminrenderer">AdminRenderer</a></h2>
|
|
<p>To include <code>AdminRenderer</code> simply add it to your settings:</p>
|
|
<pre><code>REST_FRAMEWORK = {
|
|
'DEFAULT_RENDERER_CLASSES': [
|
|
'rest_framework.renderers.JSONRenderer',
|
|
'rest_framework.renderers.AdminRenderer',
|
|
'rest_framework.renderers.BrowsableAPIRenderer'
|
|
],
|
|
'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.PageNumberPagination',
|
|
'PAGE_SIZE': 100
|
|
}
|
|
</code></pre>
|
|
<p>There are some limitations to the <code>AdminRenderer</code>, in particular it is not yet able to handle list or dictionary inputs, as we do not have any HTML form fields that support those.</p>
|
|
<p>Also note that this is an initial release and we do not yet have a public API for modifying the behavior or documentation on overriding the templates.</p>
|
|
<p>The idea is to get this released to users early, so we can start getting feedback and release a more fully featured version in 3.3.</p>
|
|
<h2 id="supported-versions"><a class="toclink" href="#supported-versions">Supported versions</a></h2>
|
|
<p>This release drops support for Django 1.4.</p>
|
|
<p>Our supported Django versions are now 1.5.6+, 1.6.3+, 1.7 and 1.8.</p>
|
|
<h2 id="deprecations"><a class="toclink" href="#deprecations">Deprecations</a></h2>
|
|
<p>There are no new deprecations in 3.2, although a number of existing deprecations have now escalated in line with our deprecation policy.</p>
|
|
<ul>
|
|
<li><code>request.DATA</code> was put on the deprecation path in 3.0. It has now been removed and its usage will result in an error. Use the more pythonic style of <code>request.data</code> instead.</li>
|
|
<li><code>request.QUERY_PARAMS</code> was put on the deprecation path in 3.0. It has now been removed and its usage will result in an error. Use the more pythonic style of <code>request.query_params</code> instead.</li>
|
|
<li>The following <code>ModelSerializer.Meta</code> options have now been removed: <code>write_only_fields</code>, <code>view_name</code>, <code>lookup_field</code>. Use the more general <code>extra_kwargs</code> option instead.</li>
|
|
</ul>
|
|
<p>The following pagination view attributes and settings have been moved into attributes on the pagination class since 3.1. Their usage was formerly in 'pending deprecation', and has now escalated to 'deprecated'. They will continue to function but will raise errors.</p>
|
|
<ul>
|
|
<li><code>view.paginate_by</code> - Use <code>paginator.page_size</code> instead.</li>
|
|
<li><code>view.page_query_param</code> - Use <code>paginator.page_query_param</code> instead.</li>
|
|
<li><code>view.paginate_by_param</code> - Use <code>paginator.page_size_query_param</code> instead.</li>
|
|
<li><code>view.max_paginate_by</code> - Use <code>paginator.max_page_size</code> instead.</li>
|
|
<li><code>settings.PAGINATE_BY</code> - Use <code>paginator.page_size</code> instead.</li>
|
|
<li><code>settings.PAGINATE_BY_PARAM</code> - Use <code>paginator.page_size_query_param</code> instead.</li>
|
|
<li><code>settings.MAX_PAGINATE_BY</code> - Use <code>paginator.max_page_size</code> instead.</li>
|
|
</ul>
|
|
<h2 id="modifications-to-list-behaviors"><a class="toclink" href="#modifications-to-list-behaviors">Modifications to list behaviors</a></h2>
|
|
<p>There are a couple of bug fixes that are worth calling out as they introduce differing behavior.</p>
|
|
<p>These are a little subtle and probably won't affect most users, but are worth understanding before upgrading your project.</p>
|
|
<h3 id="manytomany-fields-and-blanktrue"><a class="toclink" href="#manytomany-fields-and-blanktrue">ManyToMany fields and blank=True</a></h3>
|
|
<p>We've now added an <code>allow_empty</code> argument, which can be used with <code>ListSerializer</code>, or with <code>many=True</code> relationships. This is <code>True</code> by default, but can be set to <code>False</code> if you want to disallow empty lists as valid input.</p>
|
|
<p>As a follow-up to this we are now able to properly mirror the behavior of Django's <code>ModelForm</code> with respect to how many-to-many fields are validated.</p>
|
|
<p>Previously a many-to-many field on a model would map to a serializer field that would allow either empty or non-empty list inputs. Now, a many-to-many field will map to a serializer field that requires at least one input, unless the model field has <code>blank=True</code> set.</p>
|
|
<p>Here's what the mapping looks like in practice:</p>
|
|
<ul>
|
|
<li><code>models.ManyToManyField()</code> → <code>serializers.PrimaryKeyRelatedField(many=True, allow_empty=False)</code></li>
|
|
<li><code>models.ManyToManyField(blank=True)</code> → <code>serializers.PrimaryKeyRelatedField(many=True)</code></li>
|
|
</ul>
|
|
<p>The upshot is this: If you have many to many fields in your models, then make sure you've included the argument <code>blank=True</code> if you want to allow empty inputs in the equivalent <code>ModelSerializer</code> fields.</p>
|
|
<h3 id="list-fields-and-allow_null"><a class="toclink" href="#list-fields-and-allow_null">List fields and allow_null</a></h3>
|
|
<p>When using <code>allow_null</code> with <code>ListField</code> or a nested <code>many=True</code> serializer the previous behavior was to allow <code>null</code> values as items in the list. The behavior is now to allow <code>null</code> values instead of the list.</p>
|
|
<p>For example, take the following field:</p>
|
|
<pre><code>NestedSerializer(many=True, allow_null=True)
|
|
</code></pre>
|
|
<p>Previously the validation behavior would be:</p>
|
|
<ul>
|
|
<li><code>[{…}, null, {…}]</code> is <strong>valid</strong>.</li>
|
|
<li><code>null</code> is <strong>invalid</strong>.</li>
|
|
</ul>
|
|
<p>Our validation behavior as of 3.2.0 is now:</p>
|
|
<ul>
|
|
<li><code>[{…}, null, {…}]</code> is <strong>invalid</strong>.</li>
|
|
<li><code>null</code> is <strong>valid</strong>.</li>
|
|
</ul>
|
|
<p>If you want to allow <code>null</code> child items, you'll need to instead specify <code>allow_null</code> on the child class, using an explicit <code>ListField</code> instead of <code>many=True</code>. For example:</p>
|
|
<pre><code>ListField(child=NestedSerializer(allow_null=True))
|
|
</code></pre>
|
|
<h2 id="whats-next"><a class="toclink" href="#whats-next">What's next?</a></h2>
|
|
<p>The 3.3 release is currently planned for the start of October, and will be the last Kickstarter-funded release.</p>
|
|
<p>This release is planned to include:</p>
|
|
<ul>
|
|
<li>Search and filtering controls in the browsable API and admin interface.</li>
|
|
<li>Improvements and public API for the admin interface.</li>
|
|
<li>Improvements and public API for our templated HTML forms and fields.</li>
|
|
<li>Nested object and list support in HTML forms.</li>
|
|
</ul>
|
|
<p>Thanks once again to all our sponsors and supporters.</p>
|
|
|
|
|
|
</div> <!--/span-->
|
|
</div> <!--/row-->
|
|
</div> <!--/.fluid-container-->
|
|
</div> <!--/.body content-->
|
|
<div id="push"></div>
|
|
</div> <!--/.wrapper -->
|
|
|
|
<footer class="span12">
|
|
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.
|
|
</p>
|
|
</footer>
|
|
|
|
<!-- Le javascript
|
|
================================================== -->
|
|
<!-- Placed at the end of the document so the pages load faster -->
|
|
<script src="../../js/jquery-1.8.1-min.js"></script>
|
|
<script src="../../js/prettify-1.0.js"></script>
|
|
<script src="../../js/bootstrap-2.1.1-min.js"></script>
|
|
<script src="https://fund.django-rest-framework.org/sidebar_include.js"></script>
|
|
<script>var base_url = '../..';</script>
|
|
<script src="../../mkdocs/js/require.js"></script>
|
|
<script src="../../js/theme.js"></script>
|
|
|
|
<script>
|
|
var shiftWindow = function() {
|
|
scrollBy(0, -50)
|
|
};
|
|
|
|
if (location.hash) shiftWindow();
|
|
window.addEventListener("hashchange", shiftWindow);
|
|
|
|
$('.dropdown-menu').on('click touchstart', function(event) {
|
|
event.stopPropagation();
|
|
});
|
|
|
|
// Dynamically force sidenav/dropdown to no higher than browser window
|
|
$('.side-nav, .dropdown-menu').css('max-height', window.innerHeight - 130);
|
|
|
|
$(function() {
|
|
$(window).resize(function() {
|
|
$('.side-nav, .dropdown-menu').css('max-height', window.innerHeight - 130);
|
|
});
|
|
});
|
|
</script>
|
|
</body>
|
|
|
|
</html> |