encode/django-rest-framework
1
1
Fork 0
mirror of https://github.com/encode/django-rest-framework.git synced 2024-09-21 11:29:01 +03:00
Code Issues Packages Projects Releases Wiki Activity

Update documentation

Browse Source
This commit is contained in:
Tom Christie 2015-10-28 11:35:39 +00:00
parent afc7cb8ee1
commit 5bbec106d9
61 changed files with 2636 additions and 241 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
404.html
View File

@ -245,6 +245,10 @@
<a href="topics/ajax-csrf-cors/">AJAX, CSRF & CORS</a>
</li>
<li >
<a href="topics/html-and-forms/">HTML & Forms</a>
</li>
<li >
<a href="topics/browser-enhancements/">Browser Enhancements</a>
</li>
@ -281,6 +285,10 @@
<a href="topics/3.2-announcement/">3.2 Announcement</a>
</li>
<li >
<a href="topics/3.3-announcement/">3.3 Announcement</a>
</li>
<li >
<a href="topics/kickstarter-announcement/">Kickstarter Announcement</a>
</li>
@ -356,7 +364,7 @@
</div> <!--/.wrapper -->
<footer class="span12">
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.</a>
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.
</p>
</footer>

16
api-guide/authentication/index.html
View File

@ -245,6 +245,10 @@
<a href="../../topics/ajax-csrf-cors/">AJAX, CSRF & CORS</a>
</li>
<li >
<a href="../../topics/html-and-forms/">HTML & Forms</a>
</li>
<li >
<a href="../../topics/browser-enhancements/">Browser Enhancements</a>
</li>
@ -281,6 +285,10 @@
<a href="../../topics/3.2-announcement/">3.2 Announcement</a>
</li>
<li >
<a href="../../topics/3.3-announcement/">3.3 Announcement</a>
</li>
<li >
<a href="../../topics/kickstarter-announcement/">Kickstarter Announcement</a>
</li>
@ -423,6 +431,10 @@
<a href="#django-rest-auth">django-rest-auth</a>
</li>
<li>
<a href="#django-rest-framework-social-oauth2">django-rest-framework-social-oauth2</a>
</li>
<li>
<a href="#django-rest-knox">django-rest-knox</a>
</li>
@ -700,6 +712,8 @@ REST_FRAMEWORK = {
<p><a href="https://github.com/sunscrapers/djoser">Djoser</a> library provides a set of views to handle basic actions such as registration, login, logout, password reset and account activation. The package works with a custom user model and it uses token based authentication. This is a ready to use REST implementation of Django authentication system.</p>
<h2 id="django-rest-auth">django-rest-auth</h2>
<p><a href="https://github.com/Tivix/django-rest-auth">Django-rest-auth</a> library provides a set of REST API endpoints for registration, authentication (including social media authentication), password reset, retrieve and update user details, etc. By having these API endpoints, your client apps such as AngularJS, iOS, Android, and others can communicate to your Django backend site independently via REST APIs for user management.</p>
<h2 id="django-rest-framework-social-oauth2">django-rest-framework-social-oauth2</h2>
<p><a href="https://github.com/PhilipGarnero/django-rest-framework-social-oauth2">Django-rest-framework-social-oauth2</a> library provides an easy way to integrate social plugins (facebook, twitter, google, etc.) to your authentication system and an easy oauth2 setup. With this library, you will be able to authenticate users based on external tokens (e.g. facebook access token), convert these tokens to "in-house" oauth2 tokens and use and generate oauth2 tokens to authenticate your users.</p>
<h2 id="django-rest-knox">django-rest-knox</h2>
<p><a href="https://github.com/James1345/django-rest-knox">Django-rest-knox</a> library provides models and views to handle token based authentication in a more secure and extensible way than the built-in TokenAuthentication scheme - with Single Page Applications and Mobile clients in mind. It provides per-client tokens, and views to generate them when provided some other authentication (usually basic authentication), to delete the token (providing a server enforced logout) and to delete all tokens (logs out all clients that a user is logged into).</p>
@ -712,7 +726,7 @@ REST_FRAMEWORK = {
</div> <!--/.wrapper -->
<footer class="span12">
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.</a>
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.
</p>
</footer>

10
api-guide/content-negotiation/index.html
View File

@ -245,6 +245,10 @@
<a href="../../topics/ajax-csrf-cors/">AJAX, CSRF & CORS</a>
</li>
<li >
<a href="../../topics/html-and-forms/">HTML & Forms</a>
</li>
<li >
<a href="../../topics/browser-enhancements/">Browser Enhancements</a>
</li>
@ -281,6 +285,10 @@
<a href="../../topics/3.2-announcement/">3.2 Announcement</a>
</li>
<li >
<a href="../../topics/3.3-announcement/">3.3 Announcement</a>
</li>
<li >
<a href="../../topics/kickstarter-announcement/">Kickstarter Announcement</a>
</li>
@ -455,7 +463,7 @@ class NoNegotiationView(APIView):
</div> <!--/.wrapper -->
<footer class="span12">
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.</a>
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.
</p>
</footer>

10
api-guide/exceptions/index.html
View File

@ -245,6 +245,10 @@
<a href="../../topics/ajax-csrf-cors/">AJAX, CSRF & CORS</a>
</li>
<li >
<a href="../../topics/html-and-forms/">HTML & Forms</a>
</li>
<li >
<a href="../../topics/browser-enhancements/">Browser Enhancements</a>
</li>
@ -281,6 +285,10 @@
<a href="../../topics/3.2-announcement/">3.2 Announcement</a>
</li>
<li >
<a href="../../topics/3.3-announcement/">3.3 Announcement</a>
</li>
<li >
<a href="../../topics/kickstarter-announcement/">Kickstarter Announcement</a>
</li>
@ -555,7 +563,7 @@ class ServiceUnavailable(APIException):
</div> <!--/.wrapper -->
<footer class="span12">
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.</a>
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.
</p>
</footer>

28
api-guide/fields/index.html
View File

@ -245,6 +245,10 @@
<a href="../../topics/ajax-csrf-cors/">AJAX, CSRF & CORS</a>
</li>
<li >
<a href="../../topics/html-and-forms/">HTML & Forms</a>
</li>
<li >
<a href="../../topics/browser-enhancements/">Browser Enhancements</a>
</li>
@ -281,6 +285,10 @@
<a href="../../topics/3.2-announcement/">3.2 Announcement</a>
</li>
<li >
<a href="../../topics/3.3-announcement/">3.3 Announcement</a>
</li>
<li >
<a href="../../topics/kickstarter-announcement/">Kickstarter Announcement</a>
</li>
@ -479,6 +487,10 @@
<a href="#dictfield">DictField</a>
</li>
<li>
<a href="#jsonfield">JSONField</a>
</li>
<li class="main">
<a href="#miscellaneous-fields">Miscellaneous fields</a>
@ -586,7 +598,7 @@ Set to false if this field is not required to be present during deserialization.
<p>May be set to a function or other callable, in which case the value will be evaluated each time it is used. When called, it will receive no arguments. If the callable has a <code>set_context</code> method, that will be called each time before getting the value with the field instance as only argument. This works the same way as for <a href="../validators/#using-set_context">validators</a>.</p>
<p>Note that setting a <code>default</code> value implies that the field is not required. Including both the <code>default</code> and <code>required</code> keyword arguments is invalid and will raise an error.</p>
<h3 id="source"><code>source</code></h3>
<p>The name of the attribute that will be used to populate the field. May be a method that only takes a <code>self</code> argument, such as <code>URLField('get_absolute_url')</code>, or may use dotted notation to traverse attributes, such as <code>EmailField(source='user.email')</code>.</p>
<p>The name of the attribute that will be used to populate the field. May be a method that only takes a <code>self</code> argument, such as <code>URLField(source='get_absolute_url')</code>, or may use dotted notation to traverse attributes, such as <code>EmailField(source='user.email')</code>.</p>
<p>The value <code>source='*'</code> has a special meaning, and is used to indicate that the entire object should be passed through to the field. This can be useful for creating nested representations, or for fields which require access to the complete object in order to determine the output representation.</p>
<p>Defaults to the name of the field.</p>
<h3 id="validators"><code>validators</code></h3>
@ -600,8 +612,8 @@ Set to false if this field is not required to be present during deserialization.
<h3 id="initial"><code>initial</code></h3>
<p>A value that should be used for pre-populating the value of HTML form fields.</p>
<h3 id="style"><code>style</code></h3>
<p>A dictionary of key-value pairs that can be used to control how renderers should render the field. The API for this should still be considered experimental, and will be formalized with the 3.1 release.</p>
<p>Two options are currently used in HTML form generation, <code>'input_type'</code> and <code>'base_template'</code>.</p>
<p>A dictionary of key-value pairs that can be used to control how renderers should render the field.</p>
<p>Two examples here are <code>'input_type'</code> and <code>'base_template'</code>:</p>
<pre><code># Use &lt;input type="password"&gt; for the input.
password = serializers.CharField(
style={'input_type': 'password'}
@ -613,7 +625,7 @@ color_channel = serializers.ChoiceField(
style = {'base_template': 'radio.html'}
}
</code></pre>
<p><strong>Note</strong>: The <code>style</code> argument replaces the old-style version 2.x <code>widget</code> keyword argument. Because REST framework 3 now uses templated HTML form generation, the <code>widget</code> option that was used to support Django built-in widgets can no longer be supported. Version 3.3 is planned to include public API support for customizing HTML form generation.</p>
<p>For more details see the <a href="../../topics/html-and-forms/">HTML &amp; Forms</a> documentation.</p>
<hr />
<h1 id="boolean-fields">Boolean fields</h1>
<h2 id="booleanfield">BooleanField</h2>
@ -856,6 +868,12 @@ Django's regular <a href="https://docs.djangoproject.com/en/dev/ref/settings/#st
<pre><code>class DocumentField(DictField):
child = CharField()
</code></pre>
<h2 id="jsonfield">JSONField</h2>
<p>A field class that validates that the incoming data structure consists of valid JSON primitives. In its alternate binary mode, it will represent and validate JSON-encoded binary strings.</p>
<p><strong>Signature</strong>: <code>JSONField(binary)</code></p>
<ul>
<li><code>binary</code> - If set to <code>True</code> then the field will output and validate a JSON encoded string, rather that a primitive data structure. Defaults to <code>False</code>.</li>
</ul>
<hr />
<h1 id="miscellaneous-fields">Miscellaneous fields</h1>
<h2 id="readonlyfield">ReadOnlyField</h2>
@ -1009,7 +1027,7 @@ def to_internal_value(self, data):
</div> <!--/.wrapper -->
<footer class="span12">
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.</a>
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.
</p>
</footer>

31
api-guide/filtering/index.html
View File

@ -245,6 +245,10 @@
<a href="../../topics/ajax-csrf-cors/">AJAX, CSRF & CORS</a>
</li>
<li >
<a href="../../topics/html-and-forms/">HTML & Forms</a>
</li>
<li >
<a href="../../topics/browser-enhancements/">Browser Enhancements</a>
</li>
@ -281,6 +285,10 @@
<a href="../../topics/3.2-announcement/">3.2 Announcement</a>
</li>
<li >
<a href="../../topics/3.3-announcement/">3.3 Announcement</a>
</li>
<li >
<a href="../../topics/kickstarter-announcement/">Kickstarter Announcement</a>
</li>
@ -399,6 +407,10 @@
<a href="#example">Example</a>
</li>
<li>
<a href="#customizing-the-interface">Customizing the interface</a>
</li>
<li class="main">
<a href="#third-party-packages">Third party packages</a>
@ -499,6 +511,8 @@ class PurchaseList(generics.ListAPIView):
<hr />
<h1 id="generic-filtering">Generic Filtering</h1>
<p>As well as being able to override the default queryset, REST framework also includes support for generic filtering backends that allow you to easily construct complex searches and filters.</p>
<p>Generic filters can also present themselves as HTML controls in the browsable API and admin API.</p>
<p><img alt="Filter Example" src="../../img/filter-controls.png" /></p>
<h2 id="setting-filter-backends">Setting filter backends</h2>
<p>The default filter backends may be set globally, using the <code>DEFAULT_FILTER_BACKENDS</code> setting. For example.</p>
<pre><code>REST_FRAMEWORK = {
@ -544,6 +558,11 @@ class UserListView(generics.ListAPIView):
<p>To use REST framework's <code>DjangoFilterBackend</code>, first install <code>django-filter</code>.</p>
<pre><code>pip install django-filter
</code></pre>
<p>If you are using the browsable API or admin API you may also want to install <code>crispy-forms</code>, which will enhance the presentation of the filter forms in HTML views, by allowing them to render Bootstrap 3 HTML.</p>
<pre><code>pip install django-crispy-forms
</code></pre>
<p>With crispy forms installed, the browsable API will present a filtering control for <code>DjangoFilterBackend</code>, like so:</p>
<p><img alt="Django Filter" src="../../../docs/img/django-filter.png" /></p>
<h4 id="specifying-filter-fields">Specifying filter fields</h4>
<p>If all you need is simple equality-based filtering, you can set a <code>filter_fields</code> attribute on the view, or viewset, listing the set of fields you wish to filter against.</p>
<pre><code>class ProductList(generics.ListAPIView):
@ -623,6 +642,8 @@ class ProductFilter(django_filters.FilterSet):
<hr />
<h2 id="searchfilter">SearchFilter</h2>
<p>The <code>SearchFilter</code> class supports simple single query parameter based searching, and is based on the <a href="https://docs.djangoproject.com/en/dev/ref/contrib/admin/#django.contrib.admin.ModelAdmin.search_fields">Django admin's search functionality</a>.</p>
<p>When in use, the browsable API will include a <code>SearchFilter</code> control:</p>
<p><img alt="Search Filter" src="../../../docs/img/search-filter.png" /></p>
<p>The <code>SearchFilter</code> class will only be applied if the view has a <code>search_fields</code> attribute set. The <code>search_fields</code> attribute should be a list of names of text type fields on the model, such as <code>CharField</code> or <code>TextField</code>.</p>
<pre><code>class UserListView(generics.ListAPIView):
queryset = User.objects.all()
@ -651,7 +672,9 @@ class ProductFilter(django_filters.FilterSet):
<p>For more details, see the <a href="https://docs.djangoproject.com/en/dev/ref/contrib/admin/#django.contrib.admin.ModelAdmin.search_fields">Django documentation</a>.</p>
<hr />
<h2 id="orderingfilter">OrderingFilter</h2>
<p>The <code>OrderingFilter</code> class supports simple query parameter controlled ordering of results. By default, the query parameter is named <code>'ordering'</code>, but this may by overridden with the <code>ORDERING_PARAM</code> setting.</p>
<p>The <code>OrderingFilter</code> class supports simple query parameter controlled ordering of results.</p>
<p><img alt="Ordering Filter" src="../../../docs/img/ordering-filter.png" /></p>
<p>By default, the query parameter is named <code>'ordering'</code>, but this may by overridden with the <code>ORDERING_PARAM</code> setting.</p>
<p>For example, to order users by username:</p>
<pre><code>http://example.com/api/users?ordering=username
</code></pre>
@ -737,6 +760,10 @@ class ProductFilter(django_filters.FilterSet):
return queryset.filter(owner=request.user)
</code></pre>
<p>We could achieve the same behavior by overriding <code>get_queryset()</code> on the views, but using a filter backend allows you to more easily add this restriction to multiple views, or to apply it across the entire API.</p>
<h2 id="customizing-the-interface">Customizing the interface</h2>
<p>Generic filters may also present an interface in the browsable API. To do so you should implement a <code>to_html()</code> method which returns a rendered HTML representation of the filter. This method should have the following signature:</p>
<p><code>to_html(self, request, queryset, view)</code></p>
<p>The method should return a rendered HTML string.</p>
<h1 id="third-party-packages">Third party packages</h1>
<p>The following third party packages provide additional filter implementations.</p>
<h2 id="django-rest-framework-filters-package">Django REST framework filters package</h2>
@ -755,7 +782,7 @@ class ProductFilter(django_filters.FilterSet):
</div> <!--/.wrapper -->
<footer class="span12">
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.</a>
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.
</p>
</footer>

19
api-guide/format-suffixes/index.html
View File

@ -245,6 +245,10 @@
<a href="../../topics/ajax-csrf-cors/">AJAX, CSRF & CORS</a>
</li>
<li >
<a href="../../topics/html-and-forms/">HTML & Forms</a>
</li>
<li >
<a href="../../topics/browser-enhancements/">Browser Enhancements</a>
</li>
@ -281,6 +285,10 @@
<a href="../../topics/3.2-announcement/">3.2 Announcement</a>
</li>
<li >
<a href="../../topics/3.3-announcement/">3.3 Announcement</a>
</li>
<li >
<a href="../../topics/kickstarter-announcement/">Kickstarter Announcement</a>
</li>
@ -341,6 +349,10 @@
<a href="#format_suffix_patterns">format_suffix_patterns</a>
</li>
<li>
<a href="#query-parameter-formats">Query parameter formats</a>
</li>
<li>
<a href="#accept-headers-vs-format-suffixes">Accept headers vs. format suffixes</a>
</li>
@ -418,6 +430,11 @@ urlpatterns = i18n_patterns(
)
</code></pre>
<hr />
<h2 id="query-parameter-formats">Query parameter formats</h2>
<p>An alternative to the format suffixes is to include the requested format in a query parameter. REST framework provides this option by default, and it is used in the browsable API to switch between differing available representations.</p>
<p>To select a representation using its short format, use the <code>format</code> query parameter. For example: <code>http://example.com/organizations/?format=csv</code>.</p>
<p>The name of this query parameter can be modified using the <code>URL_FORMAT_OVERRIDE</code> setting. Set the value to <code>None</code> to disable this behavior.</p>
<hr />
<h2 id="accept-headers-vs-format-suffixes">Accept headers vs. format suffixes</h2>
<p>There seems to be a view among some of the Web community that filename extensions are not a RESTful pattern, and that <code>HTTP Accept</code> headers should always be used instead.</p>
<p>It is actually a misconception. For example, take the following quote from Roy Fielding discussing the relative merits of query parameter media-type indicators vs. file extension media-type indicators:</p>
@ -433,7 +450,7 @@ urlpatterns = i18n_patterns(
</div> <!--/.wrapper -->
<footer class="span12">
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.</a>
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.
</p>
</footer>

10
api-guide/generic-views/index.html
View File

@ -245,6 +245,10 @@
<a href="../../topics/ajax-csrf-cors/">AJAX, CSRF & CORS</a>
</li>
<li >
<a href="../../topics/html-and-forms/">HTML & Forms</a>
</li>
<li >
<a href="../../topics/browser-enhancements/">Browser Enhancements</a>
</li>
@ -281,6 +285,10 @@
<a href="../../topics/3.2-announcement/">3.2 Announcement</a>
</li>
<li >
<a href="../../topics/3.3-announcement/">3.3 Announcement</a>
</li>
<li >
<a href="../../topics/kickstarter-announcement/">Kickstarter Announcement</a>
</li>
@ -758,7 +766,7 @@ class BaseRetrieveUpdateDestroyView(MultipleFieldLookupMixin,
</div> <!--/.wrapper -->
<footer class="span12">
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.</a>
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.
</p>
</footer>

10
api-guide/metadata/index.html
View File

@ -245,6 +245,10 @@
<a href="../../topics/ajax-csrf-cors/">AJAX, CSRF & CORS</a>
</li>
<li >
<a href="../../topics/html-and-forms/">HTML & Forms</a>
</li>
<li >
<a href="../../topics/browser-enhancements/">Browser Enhancements</a>
</li>
@ -281,6 +285,10 @@
<a href="../../topics/3.2-announcement/">3.2 Announcement</a>
</li>
<li >
<a href="../../topics/3.3-announcement/">3.3 Announcement</a>
</li>
<li >
<a href="../../topics/kickstarter-announcement/">Kickstarter Announcement</a>
</li>
@ -468,7 +476,7 @@ def schema(self, request):
</div> <!--/.wrapper -->
<footer class="span12">
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.</a>
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.
</p>
</footer>

10
api-guide/pagination/index.html
View File

@ -245,6 +245,10 @@
<a href="../../topics/ajax-csrf-cors/">AJAX, CSRF & CORS</a>
</li>
<li >
<a href="../../topics/html-and-forms/">HTML & Forms</a>
</li>
<li >
<a href="../../topics/browser-enhancements/">Browser Enhancements</a>
</li>
@ -281,6 +285,10 @@
<a href="../../topics/3.2-announcement/">3.2 Announcement</a>
</li>
<li >
<a href="../../topics/3.3-announcement/">3.3 Announcement</a>
</li>
<li >
<a href="../../topics/kickstarter-announcement/">Kickstarter Announcement</a>
</li>
@ -662,7 +670,7 @@ class StandardResultsSetPagination(PageNumberPagination):
</div> <!--/.wrapper -->
<footer class="span12">
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.</a>
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.
</p>
</footer>

10
api-guide/parsers/index.html
View File

@ -245,6 +245,10 @@
<a href="../../topics/ajax-csrf-cors/">AJAX, CSRF & CORS</a>
</li>
<li >
<a href="../../topics/html-and-forms/">HTML & Forms</a>
</li>
<li >
<a href="../../topics/browser-enhancements/">Browser Enhancements</a>
</li>
@ -281,6 +285,10 @@
<a href="../../topics/3.2-announcement/">3.2 Announcement</a>
</li>
<li >
<a href="../../topics/3.3-announcement/">3.3 Announcement</a>
</li>
<li >
<a href="../../topics/kickstarter-announcement/">Kickstarter Announcement</a>
</li>
@ -586,7 +594,7 @@ def example_view(request, format=None):
</div> <!--/.wrapper -->
<footer class="span12">
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.</a>
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.
</p>
</footer>

10
api-guide/permissions/index.html
View File

@ -245,6 +245,10 @@
<a href="../../topics/ajax-csrf-cors/">AJAX, CSRF & CORS</a>
</li>
<li >
<a href="../../topics/html-and-forms/">HTML & Forms</a>
</li>
<li >
<a href="../../topics/browser-enhancements/">Browser Enhancements</a>
</li>
@ -281,6 +285,10 @@
<a href="../../topics/3.2-announcement/">3.2 Announcement</a>
</li>
<li >
<a href="../../topics/3.3-announcement/">3.3 Announcement</a>
</li>
<li >
<a href="../../topics/kickstarter-announcement/">Kickstarter Announcement</a>
</li>
@ -625,7 +633,7 @@ class BlacklistPermission(permissions.BasePermission):
</div> <!--/.wrapper -->
<footer class="span12">
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.</a>
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.
</p>
</footer>

12
api-guide/relations/index.html
View File

@ -245,6 +245,10 @@
<a href="../../topics/ajax-csrf-cors/">AJAX, CSRF & CORS</a>
</li>
<li >
<a href="../../topics/html-and-forms/">HTML & Forms</a>
</li>
<li >
<a href="../../topics/browser-enhancements/">Browser Enhancements</a>
</li>
@ -281,6 +285,10 @@
<a href="../../topics/3.2-announcement/">3.2 Announcement</a>
</li>
<li >
<a href="../../topics/3.3-announcement/">3.3 Announcement</a>
</li>
<li >
<a href="../../topics/kickstarter-announcement/">Kickstarter Announcement</a>
</li>
@ -699,7 +707,7 @@ class AlbumSerializer(serializers.ModelSerializer):
}
</code></pre>
<h1 id="writable-nested-serializers">Writable nested serializers</h1>
<p>Be default nested serializers are read-only. If you want to to support write-operations to a nested serializer field you'll need to create either or both of the <code>create()</code> and/or <code>update()</code> methods, in order to explicitly specify how the child relationships should be saved.</p>
<p>By default nested serializers are read-only. If you want to support write-operations to a nested serializer field you'll need to create <code>create()</code> and/or <code>update()</code> methods in order to explicitly specify how the child relationships should be saved.</p>
<pre><code>class TrackSerializer(serializers.ModelSerializer):
class Meta:
model = Track
@ -940,7 +948,7 @@ to <code>True</code>.</p>
</div> <!--/.wrapper -->
<footer class="span12">
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.</a>
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.
</p>
</footer>

25
api-guide/renderers/index.html
View File

@ -245,6 +245,10 @@
<a href="../../topics/ajax-csrf-cors/">AJAX, CSRF & CORS</a>
</li>
<li >
<a href="../../topics/html-and-forms/">HTML & Forms</a>
</li>
<li >
<a href="../../topics/browser-enhancements/">Browser Enhancements</a>
</li>
@ -281,6 +285,10 @@
<a href="../../topics/3.2-announcement/">3.2 Announcement</a>
</li>
<li >
<a href="../../topics/3.3-announcement/">3.3 Announcement</a>
</li>
<li >
<a href="../../topics/kickstarter-announcement/">Kickstarter Announcement</a>
</li>
@ -622,12 +630,21 @@ def simple_html_view(request):
<p><strong>.charset</strong>: <code>utf-8</code></p>
<p><strong>.template</strong>: <code>'rest_framework/admin.html'</code></p>
<h2 id="htmlformrenderer">HTMLFormRenderer</h2>
<p>Renders data returned by a serializer into an HTML form. The output of this renderer does not include the enclosing <code>&lt;form&gt;</code> tags or an submit actions, as you'll probably need those to include the desired method and URL. Also note that the <code>HTMLFormRenderer</code> does not yet support including field error messages.</p>
<p><strong>Note</strong>: The <code>HTMLFormRenderer</code> class is intended for internal use with the browsable API and admin interface. It should not be considered a fully documented or stable API. The template used by the <code>HTMLFormRenderer</code> class, and the context submitted to it <strong>may be subject to change</strong>. If you need to use this renderer class it is advised that you either make a local copy of the class and templates, or follow the release note on REST framework upgrades closely.</p>
<p>Renders data returned by a serializer into an HTML form. The output of this renderer does not include the enclosing <code>&lt;form&gt;</code> tags, a hidden CSRF input or any submit buttons.</p>
<p>This renderer is not intended to be used directly, but can instead be used in templates by passing a serializer instance to the <code>render_form</code> template tag.</p>
<pre><code>{% load rest_framework %}
&lt;form action="/submit-report/" method="post"&gt;
{% csrf_token %}
{% render_form serializer %}
&lt;input type="submit" value="Save" /&gt;
&lt;/form&gt;
</code></pre>
<p>For more information see the <a href="../../topics/html-and-forms/">HTML &amp; Forms</a> documentation.</p>
<p><strong>.media_type</strong>: <code>text/html</code></p>
<p><strong>.format</strong>: <code>'.form'</code></p>
<p><strong>.charset</strong>: <code>utf-8</code></p>
<p><strong>.template</strong>: <code>'rest_framework/form.html'</code></p>
<p><strong>.template</strong>: <code>'rest_framework/horizontal/form.html'</code></p>
<h2 id="multipartrenderer">MultiPartRenderer</h2>
<p>This renderer is used for rendering HTML multipart form data. <strong>It is not suitable as a response renderer</strong>, but is instead used for creating test requests, using REST framework's <a href="../testing/">test client and test request factory</a>.</p>
<p><strong>.media_type</strong>: <code>multipart/form-data; boundary=BoUnDaRyStRiNg</code></p>
@ -807,7 +824,7 @@ In this case you can underspecify the media types it should respond to, by using
</div> <!--/.wrapper -->
<footer class="span12">
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.</a>
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.
</p>
</footer>

10
api-guide/requests/index.html
View File

@ -245,6 +245,10 @@
<a href="../../topics/ajax-csrf-cors/">AJAX, CSRF & CORS</a>
</li>
<li >
<a href="../../topics/html-and-forms/">HTML & Forms</a>
</li>
<li >
<a href="../../topics/browser-enhancements/">Browser Enhancements</a>
</li>
@ -281,6 +285,10 @@
<a href="../../topics/3.2-announcement/">3.2 Announcement</a>
</li>
<li >
<a href="../../topics/3.3-announcement/">3.3 Announcement</a>
</li>
<li >
<a href="../../topics/kickstarter-announcement/">Kickstarter Announcement</a>
</li>
@ -512,7 +520,7 @@
</div> <!--/.wrapper -->
<footer class="span12">
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.</a>
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.
</p>
</footer>

10
api-guide/responses/index.html
View File

@ -245,6 +245,10 @@
<a href="../../topics/ajax-csrf-cors/">AJAX, CSRF & CORS</a>
</li>
<li >
<a href="../../topics/html-and-forms/">HTML & Forms</a>
</li>
<li >
<a href="../../topics/browser-enhancements/">Browser Enhancements</a>
</li>
@ -281,6 +285,10 @@
<a href="../../topics/3.2-announcement/">3.2 Announcement</a>
</li>
<li >
<a href="../../topics/3.3-announcement/">3.3 Announcement</a>
</li>
<li >
<a href="../../topics/kickstarter-announcement/">Kickstarter Announcement</a>
</li>
@ -472,7 +480,7 @@ response['Cache-Control'] = 'no-cache'
</div> <!--/.wrapper -->
<footer class="span12">
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.</a>
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.
</p>
</footer>

10
api-guide/reverse/index.html
View File

@ -245,6 +245,10 @@
<a href="../../topics/ajax-csrf-cors/">AJAX, CSRF & CORS</a>
</li>
<li >
<a href="../../topics/html-and-forms/">HTML & Forms</a>
</li>
<li >
<a href="../../topics/browser-enhancements/">Browser Enhancements</a>
</li>
@ -281,6 +285,10 @@
<a href="../../topics/3.2-announcement/">3.2 Announcement</a>
</li>
<li >
<a href="../../topics/3.3-announcement/">3.3 Announcement</a>
</li>
<li >
<a href="../../topics/kickstarter-announcement/">Kickstarter Announcement</a>
</li>
@ -411,7 +419,7 @@ class APIRootView(APIView):
</div> <!--/.wrapper -->
<footer class="span12">
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.</a>
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.
</p>
</footer>

10
api-guide/routers/index.html
View File

@ -245,6 +245,10 @@
<a href="../../topics/ajax-csrf-cors/">AJAX, CSRF & CORS</a>
</li>
<li >
<a href="../../topics/html-and-forms/">HTML & Forms</a>
</li>
<li >
<a href="../../topics/browser-enhancements/">Browser Enhancements</a>
</li>
@ -281,6 +285,10 @@
<a href="../../topics/3.2-announcement/">3.2 Announcement</a>
</li>
<li >
<a href="../../topics/3.3-announcement/">3.3 Announcement</a>
</li>
<li >
<a href="../../topics/kickstarter-announcement/">Kickstarter Announcement</a>
</li>
@ -662,7 +670,7 @@ rest.router.register_model(MyModel)
</div> <!--/.wrapper -->
<footer class="span12">
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.</a>
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.
</p>
</footer>

40
api-guide/serializers/index.html
View File

@ -245,6 +245,10 @@
<a href="../../topics/ajax-csrf-cors/">AJAX, CSRF & CORS</a>
</li>
<li >
<a href="../../topics/html-and-forms/">HTML & Forms</a>
</li>
<li >
<a href="../../topics/browser-enhancements/">Browser Enhancements</a>
</li>
@ -281,6 +285,10 @@
<a href="../../topics/3.2-announcement/">3.2 Announcement</a>
</li>
<li >
<a href="../../topics/3.3-announcement/">3.3 Announcement</a>
</li>
<li >
<a href="../../topics/kickstarter-announcement/">Kickstarter Announcement</a>
</li>
@ -763,7 +771,7 @@ class CommentSerializer(serializers.Serializer):
created = serializers.DateTimeField()
</code></pre>
<h2 id="writable-nested-representations">Writable nested representations</h2>
<p>When dealing with nested representations that support deserializing the data, an errors with nested objects will be nested under the field name of the nested object.</p>
<p>When dealing with nested representations that support deserializing the data, any errors with nested objects will be nested under the field name of the nested object.</p>
<pre><code>serializer = CommentSerializer(data={'user': {'email': 'foobar', 'username': 'doe'}, 'content': 'baz'})
serializer.is_valid()
# False
@ -822,7 +830,7 @@ serializer.errors
<p>Because the behavior of nested creates and updates can be ambiguous, and may require complex dependencies between related models, REST framework 3 requires you to always write these methods explicitly. The default <code>ModelSerializer</code> <code>.create()</code> and <code>.update()</code> methods do not include support for writable nested representations.</p>
<p>It is possible that a third party package, providing automatic support some kinds of automatic writable nested representations may be released alongside the 3.1 release.</p>
<h4 id="handling-saving-related-instances-in-model-manager-classes">Handling saving related instances in model manager classes</h4>
<p>An alternative to saving multiple related instances in the serializer is to write custom model manager classes handle creating the correct instances.</p>
<p>An alternative to saving multiple related instances in the serializer is to write custom model manager classes that handle creating the correct instances.</p>
<p>For example, suppose we wanted to ensure that <code>User</code> instances and <code>Profile</code> instances are always created together as a pair. We might write a custom manager class that looks something like this:</p>
<pre><code>class UserManager(models.Manager):
...
@ -862,7 +870,7 @@ serializer.data
# ]
</code></pre>
<h4 id="deserializing-multiple-objects">Deserializing multiple objects</h4>
<p>The default behavior for deserializing multiple objects is to support multiple object creation, but not support multiple object updates. For more information on how to support or customize either of these cases, see the <a href="#ListSerializer">ListSerializer</a> documentation below.</p>
<p>The default behavior for deserializing multiple objects is to support multiple object creation, but not support multiple object updates. For more information on how to support or customize either of these cases, see the <a href="#listserializer">ListSerializer</a> documentation below.</p>
<h2 id="including-extra-context">Including extra context</h2>
<p>There are some cases where you need to provide extra context to the serializer in addition to the object being serialized. One common case is if you're using a serializer that includes hyperlinked relations, which requires the serializer to have access to the current request so that it can properly generate fully qualified URLs.</p>
<p>You can provide arbitrary additional context by passing a <code>context</code> argument when instantiating the serializer. For example:</p>
@ -885,6 +893,7 @@ serializer.data
<pre><code>class AccountSerializer(serializers.ModelSerializer):
class Meta:
model = Account
fields = ('id', 'account_name', 'users', 'created')
</code></pre>
<p>By default, all the model fields on the class will be mapped to a corresponding serializer fields.</p>
<p>Any relationships such as foreign keys on the model will be mapped to <code>PrimaryKeyRelatedField</code>. Reverse relationships are not included by default unless explicitly included as described below.</p>
@ -900,14 +909,29 @@ AccountSerializer():
owner = PrimaryKeyRelatedField(queryset=User.objects.all())
</code></pre>
<h2 id="specifying-which-fields-to-include">Specifying which fields to include</h2>
<p>If you only want a subset of the default fields to be used in a model serializer, you can do so using <code>fields</code> or <code>exclude</code> options, just as you would with a <code>ModelForm</code>.</p>
<p>If you only want a subset of the default fields to be used in a model serializer, you can do so using <code>fields</code> or <code>exclude</code> options, just as you would with a <code>ModelForm</code>. It is strongly recommended that you explicitly set all fields that should be serialized using the <code>fields</code> attribute. This will make it less likely to result in unintentionally exposing data when your models change.</p>
<p>For example:</p>
<pre><code>class AccountSerializer(serializers.ModelSerializer):
class Meta:
model = Account
fields = ('id', 'account_name', 'users', 'created')
</code></pre>
<p>The names in the <code>fields</code> option will normally map to model fields on the model class.</p>
<p>You can also set the <code>fields</code> attribute to the special value <code>'__all__'</code> to indicate that all fields in the model should be used.</p>
<p>For example:</p>
<pre><code>class AccountSerializer(serializers.ModelSerializer):
class Meta:
model = Account
fields = '__all__'
</code></pre>
<p>You can set the <code>exclude</code> attribute to a list of fields to be excluded from the serializer.</p>
<p>For example:</p>
<pre><code>class AccountSerializer(serializers.ModelSerializer):
class Meta:
model = Account
exclude = ('users',)
</code></pre>
<p>In the example above, if the <code>Account</code> model had 3 fields <code>account_name</code>, <code>users</code>, and <code>created</code>, this will result in the fields <code>account_name</code> and <code>created</code> to be serialized.</p>
<p>The names in the <code>fields</code> and <code>exclude</code> attributes will normally map to model fields on the model class.</p>
<p>Alternatively names in the <code>fields</code> options can map to properties or methods which take no arguments that exist on the model class.</p>
<h2 id="specifying-nested-serialization">Specifying nested serialization</h2>
<p>The default <code>ModelSerializer</code> uses primary keys for relationships, but you can also easily generate nested representations using the <code>depth</code> option:</p>
@ -948,7 +972,7 @@ AccountSerializer():
<p>Please review the <a href="../../api-guide/validators/">Validators Documentation</a> for details on the <a href="../../api-guide/validators/#uniquetogethervalidator">UniqueTogetherValidator</a> and <a href="../../api-guide/validators/#currentuserdefault">CurrentUserDefault</a> classes.</p>
<hr />
<h2 id="additional-keyword-arguments">Additional keyword arguments</h2>
<p>There is also a shortcut allowing you to specify arbitrary additional keyword arguments on fields, using the <code>extra_kwargs</code> option. Similarly to <code>read_only_fields</code> this means you do not need to explicitly declare the field on the serializer.</p>
<p>There is also a shortcut allowing you to specify arbitrary additional keyword arguments on fields, using the <code>extra_kwargs</code> option. As in the case of <code>read_only_fields</code>, this means you do not need to explicitly declare the field on the serializer.</p>
<p>This option is a dictionary, mapping field names to a dictionary of keyword arguments. For example:</p>
<pre><code>class CreateUserSerializer(serializers.ModelSerializer):
class Meta:
@ -1148,7 +1172,7 @@ class BookSerializer(serializers.Serializer):
<li><code>.data</code> - Returns the outgoing primitive representation.</li>
<li><code>.is_valid()</code> - Deserializes and validates incoming data.</li>
<li><code>.validated_data</code> - Returns the validated incoming data.</li>
<li><code>.errors</code> - Returns an errors during validation.</li>
<li><code>.errors</code> - Returns any errors during validation.</li>
<li><code>.save()</code> - Persists the validated data into an object instance.</li>
</ul>
<p>There are four methods that can be overridden, depending on what functionality you want the serializer class to support:</p>
@ -1345,7 +1369,7 @@ def all_high_scores(request):
</div> <!--/.wrapper -->
<footer class="span12">
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.</a>
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.
</p>
</footer>

43
api-guide/settings/index.html
View File

@ -245,6 +245,10 @@
<a href="../../topics/ajax-csrf-cors/">AJAX, CSRF & CORS</a>
</li>
<li >
<a href="../../topics/html-and-forms/">HTML & Forms</a>
</li>
<li >
<a href="../../topics/browser-enhancements/">Browser Enhancements</a>
</li>
@ -281,6 +285,10 @@
<a href="../../topics/3.2-announcement/">3.2 Announcement</a>
</li>
<li >
<a href="../../topics/3.3-announcement/">3.3 Announcement</a>
</li>
<li >
<a href="../../topics/kickstarter-announcement/">Kickstarter Announcement</a>
</li>
@ -368,7 +376,7 @@
</li>
<li>
<a href="#browser-overrides">Browser overrides</a>
<a href="#content-type-controls">Content type controls</a>
</li>
<li>
@ -559,27 +567,15 @@ If set to <code>None</code> then generic filtering is disabled.</p>
)
</code></pre>
<hr />
<h2 id="browser-overrides">Browser overrides</h2>
<p><em>The following settings provide URL or form-based overrides of the default browser behavior.</em></p>
<h4 id="form_method_override">FORM_METHOD_OVERRIDE</h4>
<p>The name of a form field that may be used to override the HTTP method of the form.</p>
<p>If the value of this setting is <code>None</code> then form method overloading will be disabled.</p>
<p>Default: <code>'_method'</code></p>
<h4 id="form_content_override">FORM_CONTENT_OVERRIDE</h4>
<p>The name of a form field that may be used to override the content of the form payload. Must be used together with <code>FORM_CONTENTTYPE_OVERRIDE</code>.</p>
<p>If either setting is <code>None</code> then form content overloading will be disabled.</p>
<p>Default: <code>'_content'</code></p>
<h4 id="form_contenttype_override">FORM_CONTENTTYPE_OVERRIDE</h4>
<p>The name of a form field that may be used to override the content type of the form payload. Must be used together with <code>FORM_CONTENT_OVERRIDE</code>.</p>
<p>If either setting is <code>None</code> then form content overloading will be disabled.</p>
<p>Default: <code>'_content_type'</code></p>
<h4 id="url_accept_override">URL_ACCEPT_OVERRIDE</h4>
<p>The name of a URL parameter that may be used to override the HTTP <code>Accept</code> header.</p>
<p>If the value of this setting is <code>None</code> then URL accept overloading will be disabled.</p>
<p>Default: <code>'accept'</code></p>
<h2 id="content-type-controls">Content type controls</h2>
<h4 id="url_format_override">URL_FORMAT_OVERRIDE</h4>
<p>The name of a URL parameter that may be used to override the default <code>Accept</code> header based content negotiation.</p>
<p>If the value of this setting is <code>None</code> then URL format overloading will be disabled.</p>
<p>The name of a URL parameter that may be used to override the default content negotiation <code>Accept</code> header behavior, by using a <code>format=…</code> query parameter in the request URL.</p>
<p>For example: <code>http://example.com/organizations/?format=csv</code></p>
<p>If the value of this setting is <code>None</code> then URL format overrides will be disabled.</p>
<p>Default: <code>'format'</code></p>
<h4 id="format_suffix_kwarg">FORMAT_SUFFIX_KWARG</h4>
<p>The name of a parameter in the URL conf that may be used to provide a format suffix. This setting is applied when using <code>format_suffix_patterns</code> to include suffixed URL patterns.</p>
<p>For example: <code>http://example.com/organizations.csv/</code></p>
<p>Default: <code>'format'</code></p>
<hr />
<h2 id="date-and-time-formatting">Date and time formatting</h2>
@ -674,9 +670,6 @@ If set to <code>None</code> then generic filtering is disabled.</p>
<h4 id="url_field_name">URL_FIELD_NAME</h4>
<p>A string representing the key that should be used for the URL fields generated by <code>HyperlinkedModelSerializer</code>.</p>
<p>Default: <code>'url'</code></p>
<h4 id="format_suffix_kwarg">FORMAT_SUFFIX_KWARG</h4>
<p>The name of a parameter in the URL conf that may be used to provide a format suffix.</p>
<p>Default: <code>'format'</code></p>
<h4 id="num_proxies">NUM_PROXIES</h4>
<p>An integer of 0 or more, that may be used to specify the number of application proxies that the API runs behind. This allows throttling to more accurately identify client IP addresses. If set to <code>None</code> then less strict IP matching will be used by the throttle classes.</p>
<p>Default: <code>None</code></p>
@ -690,7 +683,7 @@ If set to <code>None</code> then generic filtering is disabled.</p>
</div> <!--/.wrapper -->
<footer class="span12">
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.</a>
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.
</p>
</footer>

10
api-guide/status-codes/index.html
View File

@ -245,6 +245,10 @@
<a href="../../topics/ajax-csrf-cors/">AJAX, CSRF & CORS</a>
</li>
<li >
<a href="../../topics/html-and-forms/">HTML & Forms</a>
</li>
<li >
<a href="../../topics/browser-enhancements/">Browser Enhancements</a>
</li>
@ -281,6 +285,10 @@
<a href="../../topics/3.2-announcement/">3.2 Announcement</a>
</li>
<li >
<a href="../../topics/3.3-announcement/">3.3 Announcement</a>
</li>
<li >
<a href="../../topics/kickstarter-announcement/">Kickstarter Announcement</a>
</li>
@ -483,7 +491,7 @@ is_server_error() # 5xx
</div> <!--/.wrapper -->
<footer class="span12">
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.</a>
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.
</p>
</footer>

10
api-guide/testing/index.html
View File

@ -245,6 +245,10 @@
<a href="../../topics/ajax-csrf-cors/">AJAX, CSRF & CORS</a>
</li>
<li >
<a href="../../topics/html-and-forms/">HTML & Forms</a>
</li>
<li >
<a href="../../topics/browser-enhancements/">Browser Enhancements</a>
</li>
@ -281,6 +285,10 @@
<a href="../../topics/3.2-announcement/">3.2 Announcement</a>
</li>
<li >
<a href="../../topics/3.3-announcement/">3.3 Announcement</a>
</li>
<li >
<a href="../../topics/kickstarter-announcement/">Kickstarter Announcement</a>
</li>
@ -639,7 +647,7 @@ self.assertEqual(response.content, '{"username": "lauren", "id": 4}')
</div> <!--/.wrapper -->
<footer class="span12">
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.</a>
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.
</p>
</footer>

12
api-guide/throttling/index.html
View File

@ -245,6 +245,10 @@
<a href="../../topics/ajax-csrf-cors/">AJAX, CSRF & CORS</a>
</li>
<li >
<a href="../../topics/html-and-forms/">HTML & Forms</a>
</li>
<li >
<a href="../../topics/browser-enhancements/">Browser Enhancements</a>
</li>
@ -281,6 +285,10 @@
<a href="../../topics/3.2-announcement/">3.2 Announcement</a>
</li>
<li >
<a href="../../topics/3.3-announcement/">3.3 Announcement</a>
</li>
<li >
<a href="../../topics/kickstarter-announcement/">Kickstarter Announcement</a>
</li>
@ -536,7 +544,7 @@ class UploadView(APIView):
<p>If the <code>.wait()</code> method is implemented and the request is throttled, then a <code>Retry-After</code> header will be included in the response.</p>
<h2 id="example">Example</h2>
<p>The following is an example of a rate throttle, that will randomly throttle 1 in every 10 requests.</p>
<pre><code>class RandomRateThrottle(throttles.BaseThrottle):
<pre><code>class RandomRateThrottle(throttling.BaseThrottle):
def allow_request(self, request, view):
return random.randint(1, 10) == 1
</code></pre>
@ -550,7 +558,7 @@ class UploadView(APIView):
</div> <!--/.wrapper -->
<footer class="span12">
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.</a>
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.
</p>
</footer>

10
api-guide/validators/index.html
View File

@ -245,6 +245,10 @@
<a href="../../topics/ajax-csrf-cors/">AJAX, CSRF & CORS</a>
</li>
<li >
<a href="../../topics/html-and-forms/">HTML & Forms</a>
</li>
<li >
<a href="../../topics/browser-enhancements/">Browser Enhancements</a>
</li>
@ -281,6 +285,10 @@
<a href="../../topics/3.2-announcement/">3.2 Announcement</a>
</li>
<li >
<a href="../../topics/3.3-announcement/">3.3 Announcement</a>
</li>
<li >
<a href="../../topics/kickstarter-announcement/">Kickstarter Announcement</a>
</li>
@ -586,7 +594,7 @@ It has two required arguments, and a single optional <code>messages</code> argum
</div> <!--/.wrapper -->
<footer class="span12">
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.</a>
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.
</p>
</footer>

12
api-guide/versioning/index.html
View File

@ -245,6 +245,10 @@
<a href="../../topics/ajax-csrf-cors/">AJAX, CSRF & CORS</a>
</li>
<li >
<a href="../../topics/html-and-forms/">HTML & Forms</a>
</li>
<li >
<a href="../../topics/browser-enhancements/">Browser Enhancements</a>
</li>
@ -281,6 +285,10 @@
<a href="../../topics/3.2-announcement/">3.2 Announcement</a>
</li>
<li >
<a href="../../topics/3.3-announcement/">3.3 Announcement</a>
</li>
<li >
<a href="../../topics/kickstarter-announcement/">Kickstarter Announcement</a>
</li>
@ -452,7 +460,7 @@ reverse('bookings-list', request=request)
<ul>
<li><code>DEFAULT_VERSION</code>. The value that should be used for <code>request.version</code> when no versioning information is present. Defaults to <code>None</code>.</li>
<li><code>ALLOWED_VERSIONS</code>. If set, this value will restrict the set of versions that may be returned by the versioning scheme, and will raise an error if the provided version if not in this set. Note that the value used for the <code>DEFAULT_VERSION</code> setting is always considered to be part of the <code>ALLOWED_VERSIONS</code> set. Defaults to <code>None</code>.</li>
<li><code>VERSION_PARAMETER</code>. The string that should used for any versioning parameters, such as in the media type or URL query parameters. Defaults to <code>'version'</code>.</li>
<li><code>VERSION_PARAM</code>. The string that should used for any versioning parameters, such as in the media type or URL query parameters. Defaults to <code>'version'</code>.</li>
</ul>
<p>You can also set your versioning class plus those three values on a per-view or a per-viewset basis by defining your own versioning scheme and using the <code>default_version</code>, <code>allowed_versions</code> and <code>version_param</code> class variables. For example, if you want to use <code>URLPathVersioning</code>:</p>
<pre><code>from rest_framework.versioning import URLPathVersioning
@ -567,7 +575,7 @@ Accept: application/json
</div> <!--/.wrapper -->
<footer class="span12">
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.</a>
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.
</p>
</footer>

10
api-guide/views/index.html
View File

@ -245,6 +245,10 @@
<a href="../../topics/ajax-csrf-cors/">AJAX, CSRF & CORS</a>
</li>
<li >
<a href="../../topics/html-and-forms/">HTML & Forms</a>
</li>
<li >
<a href="../../topics/browser-enhancements/">Browser Enhancements</a>
</li>
@ -281,6 +285,10 @@
<a href="../../topics/3.2-announcement/">3.2 Announcement</a>
</li>
<li >
<a href="../../topics/3.3-announcement/">3.3 Announcement</a>
</li>
<li >
<a href="../../topics/kickstarter-announcement/">Kickstarter Announcement</a>
</li>
@ -520,7 +528,7 @@ def view(request):
</div> <!--/.wrapper -->
<footer class="span12">
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.</a>
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.
</p>
</footer>

10
api-guide/viewsets/index.html
View File

@ -245,6 +245,10 @@
<a href="../../topics/ajax-csrf-cors/">AJAX, CSRF & CORS</a>
</li>
<li >
<a href="../../topics/html-and-forms/">HTML & Forms</a>
</li>
<li >
<a href="../../topics/browser-enhancements/">Browser Enhancements</a>
</li>
@ -281,6 +285,10 @@
<a href="../../topics/3.2-announcement/">3.2 Announcement</a>
</li>
<li >
<a href="../../topics/3.3-announcement/">3.3 Announcement</a>
</li>
<li >
<a href="../../topics/kickstarter-announcement/">Kickstarter Announcement</a>
</li>
@ -608,7 +616,7 @@ class UserViewSet(viewsets.ModelViewSet):
</div> <!--/.wrapper -->
<footer class="span12">
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.</a>
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.
</p>
</footer>

BIN
img/django-filter.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 13 KiB

BIN
img/filter-controls.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 47 KiB

BIN
img/horizontal.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 11 KiB

BIN
img/inline.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 8.1 KiB

BIN
img/ordering-filter.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 18 KiB

BIN
img/search-filter.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 8.9 KiB

BIN
img/vertical.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 12 KiB

23
index.html
View File

@ -245,6 +245,10 @@
<a href="topics/ajax-csrf-cors/">AJAX, CSRF & CORS</a>
</li>
<li >
<a href="topics/html-and-forms/">HTML & Forms</a>
</li>
<li >
<a href="topics/browser-enhancements/">Browser Enhancements</a>
</li>
@ -281,6 +285,10 @@
<a href="topics/3.2-announcement/">3.2 Announcement</a>
</li>
<li >
<a href="topics/3.3-announcement/">3.3 Announcement</a>
</li>
<li >
<a href="topics/kickstarter-announcement/">Kickstarter Announcement</a>
</li>
@ -431,8 +439,7 @@
</p>
<hr />
<p><strong>Note</strong>: This is the documentation for the <strong>version 3.2</strong> of REST framework. Documentation for <a href="http://tomchristie.github.io/rest-framework-2-docs/">version 2.4</a> is also available.</p>
<p>For more details see the 3.2 <a href="topics/3.2-announcement/">announcement</a> and <a href="topics/release-notes/">release notes</a>.</p>
<p><strong>Note</strong>: This is the documentation for the <strong>version 3</strong> of REST framework. Documentation for <a href="http://tomchristie.github.io/rest-framework-2-docs/">version 2</a> is also available.</p>
<hr />
<p>
<h1 style="position: absolute;
@ -447,7 +454,7 @@
<img alt="Django REST Framework" title="Logo by Jake 'Sid' Smith" src="img/logo.png" width="600px" style="display: block; margin: 0 auto 0 auto">
</p>
<p>Django REST framework is a powerful and flexible toolkit that makes it easy to build Web APIs.</p>
<p>Django REST framework is a powerful and flexible toolkit for building Web APIs.</p>
<p>Some reasons you might want to use REST framework:</p>
<ul>
<li>The <a href="http://restframework.herokuapp.com/">Web browsable API</a> is a huge usability win for your developers.</li>
@ -463,13 +470,14 @@
<h2 id="requirements">Requirements</h2>
<p>REST framework requires the following:</p>
<ul>
<li>Python (2.6.5+, 2.7, 3.2, 3.3, 3.4)</li>
<li>Django (1.5.6+, 1.6.3+, 1.7+, 1.8)</li>
<li>Python (2.7, 3.2, 3.3, 3.4, 3.5)</li>
<li>Django (1.7+, 1.8, 1.9)</li>
</ul>
<p>The following packages are optional:</p>
<ul>
<li><a href="http://pypi.python.org/pypi/Markdown/">Markdown</a> (2.1.0+) - Markdown support for the browsable API.</li>
<li><a href="http://pypi.python.org/pypi/django-filter">django-filter</a> (0.9.2+) - Filtering support.</li>
<li>[django-crispy-forms][django-crispy-forms] - Improved HTML display for filtering.</li>
<li><a href="https://github.com/lukaszb/django-guardian">django-guardian</a> (1.1.1+) - Object level permissions support.</li>
</ul>
<h2 id="installation">Installation</h2>
@ -583,7 +591,9 @@ urlpatterns = [
<p>General guides to using REST framework.</p>
<ul>
<li><a href="topics/documenting-your-api/">Documenting your API</a></li>
<li><a href="topics/internationalization/">Internationalization</a></li>
<li><a href="topics/ajax-csrf-cors/">AJAX, CSRF &amp; CORS</a></li>
<li><a href="topics/html-and-forms/">HTML &amp; Forms</a></li>
<li><a href="topics/browser-enhancements/">Browser enhancements</a></li>
<li><a href="topics/browsable-api/">The Browsable API</a></li>
<li><a href="topics/rest-hypermedia-hateoas/">REST, Hypermedia &amp; HATEOAS</a></li>
@ -593,6 +603,7 @@ urlpatterns = [
<li><a href="topics/3.0-announcement/">3.0 Announcement</a></li>
<li><a href="topics/3.1-announcement/">3.1 Announcement</a></li>
<li><a href="topics/3.2-announcement/">3.2 Announcement</a></li>
<li><a href="topics/3.3-announcement/">3.3 Announcement</a></li>
<li><a href="topics/kickstarter-announcement/">Kickstarter Announcement</a></li>
<li><a href="topics/release-notes/">Release Notes</a></li>
</ul>
@ -639,7 +650,7 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.</p>
</div> <!--/.wrapper -->
<footer class="span12">
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.</a>
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.
</p>
</footer>

175
mkdocs/search_index.json
View File

File diff suppressed because one or more lines are too long

108
sitemap.xml
View File

@ -4,7 +4,7 @@
<url>
<loc>http://www.django-rest-framework.org//</loc>
<lastmod>2015-10-27</lastmod>
<lastmod>2015-10-28</lastmod>
<changefreq>daily</changefreq>
</url>
@ -13,43 +13,43 @@
<url>
<loc>http://www.django-rest-framework.org//tutorial/quickstart/</loc>
<lastmod>2015-10-27</lastmod>
<lastmod>2015-10-28</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//tutorial/1-serialization/</loc>
<lastmod>2015-10-27</lastmod>
<lastmod>2015-10-28</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//tutorial/2-requests-and-responses/</loc>
<lastmod>2015-10-27</lastmod>
<lastmod>2015-10-28</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//tutorial/3-class-based-views/</loc>
<lastmod>2015-10-27</lastmod>
<lastmod>2015-10-28</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//tutorial/4-authentication-and-permissions/</loc>
<lastmod>2015-10-27</lastmod>
<lastmod>2015-10-28</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//tutorial/5-relationships-and-hyperlinked-apis/</loc>
<lastmod>2015-10-27</lastmod>
<lastmod>2015-10-28</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//tutorial/6-viewsets-and-routers/</loc>
<lastmod>2015-10-27</lastmod>
<lastmod>2015-10-28</lastmod>
<changefreq>daily</changefreq>
</url>
@ -59,157 +59,157 @@
<url>
<loc>http://www.django-rest-framework.org//api-guide/requests/</loc>
<lastmod>2015-10-27</lastmod>
<lastmod>2015-10-28</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//api-guide/responses/</loc>
<lastmod>2015-10-27</lastmod>
<lastmod>2015-10-28</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//api-guide/views/</loc>
<lastmod>2015-10-27</lastmod>
<lastmod>2015-10-28</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//api-guide/generic-views/</loc>
<lastmod>2015-10-27</lastmod>
<lastmod>2015-10-28</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//api-guide/viewsets/</loc>
<lastmod>2015-10-27</lastmod>
<lastmod>2015-10-28</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//api-guide/routers/</loc>
<lastmod>2015-10-27</lastmod>
<lastmod>2015-10-28</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//api-guide/parsers/</loc>
<lastmod>2015-10-27</lastmod>
<lastmod>2015-10-28</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//api-guide/renderers/</loc>
<lastmod>2015-10-27</lastmod>
<lastmod>2015-10-28</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//api-guide/serializers/</loc>
<lastmod>2015-10-27</lastmod>
<lastmod>2015-10-28</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//api-guide/fields/</loc>
<lastmod>2015-10-27</lastmod>
<lastmod>2015-10-28</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//api-guide/relations/</loc>
<lastmod>2015-10-27</lastmod>
<lastmod>2015-10-28</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//api-guide/validators/</loc>
<lastmod>2015-10-27</lastmod>
<lastmod>2015-10-28</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//api-guide/authentication/</loc>
<lastmod>2015-10-27</lastmod>
<lastmod>2015-10-28</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//api-guide/permissions/</loc>
<lastmod>2015-10-27</lastmod>
<lastmod>2015-10-28</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//api-guide/throttling/</loc>
<lastmod>2015-10-27</lastmod>
<lastmod>2015-10-28</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//api-guide/filtering/</loc>
<lastmod>2015-10-27</lastmod>
<lastmod>2015-10-28</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//api-guide/pagination/</loc>
<lastmod>2015-10-27</lastmod>
<lastmod>2015-10-28</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//api-guide/versioning/</loc>
<lastmod>2015-10-27</lastmod>
<lastmod>2015-10-28</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//api-guide/content-negotiation/</loc>
<lastmod>2015-10-27</lastmod>
<lastmod>2015-10-28</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//api-guide/metadata/</loc>
<lastmod>2015-10-27</lastmod>
<lastmod>2015-10-28</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//api-guide/format-suffixes/</loc>
<lastmod>2015-10-27</lastmod>
<lastmod>2015-10-28</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//api-guide/reverse/</loc>
<lastmod>2015-10-27</lastmod>
<lastmod>2015-10-28</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//api-guide/exceptions/</loc>
<lastmod>2015-10-27</lastmod>
<lastmod>2015-10-28</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//api-guide/status-codes/</loc>
<lastmod>2015-10-27</lastmod>
<lastmod>2015-10-28</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//api-guide/testing/</loc>
<lastmod>2015-10-27</lastmod>
<lastmod>2015-10-28</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//api-guide/settings/</loc>
<lastmod>2015-10-27</lastmod>
<lastmod>2015-10-28</lastmod>
<changefreq>daily</changefreq>
</url>
@ -219,85 +219,97 @@
<url>
<loc>http://www.django-rest-framework.org//topics/documenting-your-api/</loc>
<lastmod>2015-10-27</lastmod>
<lastmod>2015-10-28</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//topics/internationalization/</loc>
<lastmod>2015-10-27</lastmod>
<lastmod>2015-10-28</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//topics/ajax-csrf-cors/</loc>
<lastmod>2015-10-27</lastmod>
<lastmod>2015-10-28</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//topics/html-and-forms/</loc>
<lastmod>2015-10-28</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//topics/browser-enhancements/</loc>
<lastmod>2015-10-27</lastmod>
<lastmod>2015-10-28</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//topics/browsable-api/</loc>
<lastmod>2015-10-27</lastmod>
<lastmod>2015-10-28</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//topics/rest-hypermedia-hateoas/</loc>
<lastmod>2015-10-27</lastmod>
<lastmod>2015-10-28</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//topics/third-party-resources/</loc>
<lastmod>2015-10-27</lastmod>
<lastmod>2015-10-28</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//topics/contributing/</loc>
<lastmod>2015-10-27</lastmod>
<lastmod>2015-10-28</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//topics/project-management/</loc>
<lastmod>2015-10-27</lastmod>
<lastmod>2015-10-28</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//topics/3.0-announcement/</loc>
<lastmod>2015-10-27</lastmod>
<lastmod>2015-10-28</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//topics/3.1-announcement/</loc>
<lastmod>2015-10-27</lastmod>
<lastmod>2015-10-28</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//topics/3.2-announcement/</loc>
<lastmod>2015-10-27</lastmod>
<lastmod>2015-10-28</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//topics/3.3-announcement/</loc>
<lastmod>2015-10-28</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//topics/kickstarter-announcement/</loc>
<lastmod>2015-10-27</lastmod>
<lastmod>2015-10-28</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//topics/release-notes/</loc>
<lastmod>2015-10-27</lastmod>
<lastmod>2015-10-28</lastmod>
<changefreq>daily</changefreq>
</url>

10
topics/3.0-announcement/index.html
View File

@ -245,6 +245,10 @@
<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>
@ -281,6 +285,10 @@
<a href="../3.2-announcement/">3.2 Announcement</a>
</li>
<li >
<a href="../3.3-announcement/">3.3 Announcement</a>
</li>
<li >
<a href="../kickstarter-announcement/">Kickstarter Announcement</a>
</li>
@ -1139,7 +1147,7 @@ amount = serializers.DecimalField(
</div> <!--/.wrapper -->
<footer class="span12">
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.</a>
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.
</p>
</footer>

10
topics/3.1-announcement/index.html
View File

@ -245,6 +245,10 @@
<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>
@ -281,6 +285,10 @@
<a href="../3.2-announcement/">3.2 Announcement</a>
</li>
<li >
<a href="../3.3-announcement/">3.3 Announcement</a>
</li>
<li >
<a href="../kickstarter-announcement/">Kickstarter Announcement</a>
</li>
@ -533,7 +541,7 @@ Host: example.org
</div> <!--/.wrapper -->
<footer class="span12">
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.</a>
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.
</p>
</footer>

12
topics/3.2-announcement/index.html
View File

@ -61,7 +61,7 @@
<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="../kickstarter-announcement/">
<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/">
@ -245,6 +245,10 @@
<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>
@ -281,6 +285,10 @@
<a href="./">3.2 Announcement</a>
</li>
<li >
<a href="../3.3-announcement/">3.3 Announcement</a>
</li>
<li >
<a href="../kickstarter-announcement/">Kickstarter Announcement</a>
</li>
@ -462,7 +470,7 @@
</div> <!--/.wrapper -->
<footer class="span12">
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.</a>
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.
</p>
</footer>

458
topics/3.3-announcement/index.html Normal file
View File

@ -0,0 +1,458 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta charset="utf-8">
<title>3.3 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.3-announcement/" />
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="description" content="Django, API, REST, 3.3 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>
span.fusion-wrap a {
display: block;
margin-top: 10px;
color: black;
}
a.fusion-poweredby {
display: block;
margin-top: 10px;
}
@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="../kickstarter-announcement/">
Next <i class="icon-arrow-right icon-white"></i>
</a>
<a class="repo-link btn btn-inverse btn-small " rel="next" href="../3.2-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>
</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/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="../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-resources/">Third Party 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="../3.0-announcement/">3.0 Announcement</a>
</li>
<li >
<a href="../3.1-announcement/">3.1 Announcement</a>
</li>
<li >
<a href="../3.2-announcement/">3.2 Announcement</a>
</li>
<li class="active" >
<a href="./">3.3 Announcement</a>
</li>
<li >
<a href="../kickstarter-announcement/">Kickstarter Announcement</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">&times;</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-33">Django REST framework 3.3</a>
</li>
<li>
<a href="#release-notes">Release notes</a>
</li>
<li>
<a href="#supported-versions">Supported versions</a>
</li>
<li>
<a href="#deprecations">Deprecations</a>
</li>
</ul>
</div>
</div>
<div id="main-content" class="span9">
<h1 id="django-rest-framework-33">Django REST framework 3.3</h1>
<p>The 3.3 release marks the final work in the Kickstarter funded series. We'd like to offer a final resounding <strong>thank you</strong> to all our wonderful sponsors and supporters.</p>
<p>The amount of work that has been achieved as a direct result of the funding is immense. We've added a huge amounts of new functionality, resolved nearly 2,000 tickets, and redesigned &amp; refined large parts of the project.</p>
<p>In order to continue driving REST framework forward, we'll shortly be announcing a new set of funding plans. Follow <a href="https://twitter.com/_tomchristie">@_tomchristie</a> to keep up to date with these announcements, and be among the first set of sign ups.</p>
<p>We strongly believe that collaboratively funded software development yields outstanding results for a relatively low investment-per-head. If you or your company use REST framework commercially, then we would strongly urge you to participate in this latest funding drive, and help us continue to build an increasingly polished &amp; professional product.</p>
<hr />
<h2 id="release-notes">Release notes</h2>
<p>Significant new functionality in the 3.3 release includes:</p>
<ul>
<li>Filters presented as HTML controls in the browsable API.</li>
<li>A <a href="../html-and-forms/">forms API</a>, allowing serializers to be rendered as HTML forms.</li>
<li>Django 1.9 support.</li>
<li>A <a href="../../../api-guide/fields#jsonfield"><code>JSONField</code> serializer field</a>, corresponding to Django 1.9's Postgres <code>JSONField</code> model field.</li>
<li>Browsable API support <a href="https://github.com/tomchristie/ajax-form">via AJAX</a>, rather than server side request overloading.</li>
</ul>
<p><img alt="Filter Controls" src="../../img/filter-controls.png" /></p>
<p><em>Example of the new filter controls</em></p>
<hr />
<h2 id="supported-versions">Supported versions</h2>
<p>This release drops support for Django 1.5 and 1.6. Django 1.7, 1.8 or 1.9 are now required.</p>
<p>This brings our supported versions into line with Django's <a href="https://www.djangoproject.com/download/#supported-versions">currently supported versions</a></p>
<h2 id="deprecations">Deprecations</h2>
<p>The AJAX based support for the browsable API means that there are a number of internal cleanups in the <code>request</code> class. For the vast majority of developers this should largely remain transparent:</p>
<ul>
<li>To support form based <code>PUT</code> and <code>DELETE</code>, or to support form content types such as JSON, you should now use the [AJAX forms][ajax-forms] javascript library. This replaces the previous 'method and content type overloading' that required significant internal complexity to the request class.</li>
<li>The <code>accept</code> query parameter is no longer supported by the default content negotiation class. If you require it then you'll need to <a href="../browser-enhancements/#url-based-accept-headers">use a custom content negotiation class</a>.</li>
<li>The custom <code>HTTP_X_HTTP_METHOD_OVERRIDE</code> header is no longer supported by default. If you require it then you'll need to <a href="../browser-enhancements/#http-header-based-method-overriding">use custom middleware</a>.</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 deprecated, and has now been removed entirely, in line with the deprecation policy.</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>
<p>The <code>ModelSerializer</code> and <code>HyperlinkedModelSerializer</code> classes should now include either a <code>fields</code> or <code>exclude</code> option, although the <code>fields = '__all__'</code> shortcut may be used. Failing to include either of these two options is currently pending deprecation, and will be removed entirely in the 3.5 release. This behavior brings <code>ModelSerializer</code> more closely in line with Django's <code>ModelForm</code> behavior.</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>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>

12
topics/ajax-csrf-cors/index.html
View File

@ -61,7 +61,7 @@
<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="../browser-enhancements/">
<a class="repo-link btn btn-inverse btn-small " rel="prev" href="../html-and-forms/">
Next <i class="icon-arrow-right icon-white"></i>
</a>
<a class="repo-link btn btn-inverse btn-small " rel="next" href="../internationalization/">
@ -245,6 +245,10 @@
<a href="./">AJAX, CSRF & CORS</a>
</li>
<li >
<a href="../html-and-forms/">HTML & Forms</a>
</li>
<li >
<a href="../browser-enhancements/">Browser Enhancements</a>
</li>
@ -281,6 +285,10 @@
<a href="../3.2-announcement/">3.2 Announcement</a>
</li>
<li >
<a href="../3.3-announcement/">3.3 Announcement</a>
</li>
<li >
<a href="../kickstarter-announcement/">Kickstarter Announcement</a>
</li>
@ -393,7 +401,7 @@
</div> <!--/.wrapper -->
<footer class="span12">
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.</a>
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.
</p>
</footer>

10
topics/browsable-api/index.html
View File

@ -245,6 +245,10 @@
<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>
@ -281,6 +285,10 @@
<a href="../3.2-announcement/">3.2 Announcement</a>
</li>
<li >
<a href="../3.3-announcement/">3.3 Announcement</a>
</li>
<li >
<a href="../kickstarter-announcement/">Kickstarter Announcement</a>
</li>
@ -477,7 +485,7 @@
</div> <!--/.wrapper -->
<footer class="span12">
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.</a>
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.
</p>
</footer>

100
topics/browser-enhancements/index.html
View File

@ -64,7 +64,7 @@
<a class="repo-link btn btn-inverse btn-small " rel="prev" href="../browsable-api/">
Next <i class="icon-arrow-right icon-white"></i>
</a>
<a class="repo-link btn btn-inverse btn-small " rel="next" href="../ajax-csrf-cors/">
<a class="repo-link btn btn-inverse btn-small " rel="next" href="../html-and-forms/">
<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>
@ -245,6 +245,10 @@
<a href="../ajax-csrf-cors/">AJAX, CSRF & CORS</a>
</li>
<li >
<a href="../html-and-forms/">HTML & Forms</a>
</li>
<li class="active" >
<a href="./">Browser Enhancements</a>
</li>
@ -281,6 +285,10 @@
<a href="../3.2-announcement/">3.2 Announcement</a>
</li>
<li >
<a href="../3.3-announcement/">3.3 Announcement</a>
</li>
<li >
<a href="../kickstarter-announcement/">Kickstarter Announcement</a>
</li>
@ -341,20 +349,20 @@
<a href="#browser-based-put-delete-etc">Browser based PUT, DELETE, etc...</a>
</li>
<li>
<a href="#http-header-based-method-overriding">HTTP header based method overriding</a>
</li>
<li>
<a href="#browser-based-submission-of-non-form-content">Browser based submission of non-form content</a>
</li>
<li>
<a href="#url-based-accept-headers">URL based accept headers</a>
<a href="#url-based-format-suffixes">URL based format suffixes</a>
</li>
<li>
<a href="#url-based-format-suffixes">URL based format suffixes</a>
<a href="#http-header-based-method-overriding">HTTP header based method overriding</a>
</li>
<li>
<a href="#url-based-accept-headers">URL based accept headers</a>
</li>
<li>
@ -378,49 +386,55 @@
<p>"There are two noncontroversial uses for overloaded POST. The first is to <em>simulate</em> HTTP's uniform interface for clients like web browsers that don't support PUT or DELETE"</p>
<p>&mdash; <a href="http://www.amazon.com/Restful-Web-Services-Leonard-Richardson/dp/0596529260">RESTful Web Services</a>, Leonard Richardson &amp; Sam Ruby.</p>
</blockquote>
<p>In order to allow the browsable API to function, there are a couple of browser enhancements that REST framework needs to provide.</p>
<p>As of version 3.3.0 onwards these are enabled with javascript, using the <a href="https://github.com/tomchristie/ajax-form">ajax-form</a> library.</p>
<h2 id="browser-based-put-delete-etc">Browser based PUT, DELETE, etc...</h2>
<p>REST framework supports browser-based <code>PUT</code>, <code>DELETE</code> and other methods, by
overloading <code>POST</code> requests using a hidden form field.</p>
<p>Note that this is the same strategy as is used in <a href="http://guides.rubyonrails.org/form_helpers.html#how-do-forms-with-put-or-delete-methods-work">Ruby on Rails</a>.</p>
<p>For example, given the following form:</p>
<pre><code>&lt;form action="/news-items/5" method="POST"&gt;
&lt;input type="hidden" name="_method" value="DELETE"&gt;
&lt;/form&gt;
</code></pre>
<p><code>request.method</code> would return <code>"DELETE"</code>.</p>
<h2 id="http-header-based-method-overriding">HTTP header based method overriding</h2>
<p>REST framework also supports method overriding via the semi-standard <code>X-HTTP-Method-Override</code> header. This can be useful if you are working with non-form content such as JSON and are working with an older web server and/or hosting provider that doesn't recognise particular HTTP methods such as <code>PATCH</code>. For example <a href="https://forums.aws.amazon.com/thread.jspa?messageID=400724">Amazon Web Services ELB</a>.</p>
<p>To use it, make a <code>POST</code> request, setting the <code>X-HTTP-Method-Override</code> header.</p>
<p>For example, making a <code>PATCH</code> request via <code>POST</code> in jQuery:</p>
<pre><code>$.ajax({
url: '/myresource/',
method: 'POST',
headers: {'X-HTTP-Method-Override': 'PATCH'},
<p>The <a href="https://github.com/tomchristie/ajax-form">AJAX form library</a> supports browser-based <code>PUT</code>, <code>DELETE</code> and other methods on HTML forms.</p>
<p>After including the library, use the <code>data-method</code> attribute on the form, like so:</p>
<pre><code>&lt;form action="/" data-method="PUT"&gt;
&lt;input name='foo'/&gt;
...
});
</code></pre>
<h2 id="browser-based-submission-of-non-form-content">Browser based submission of non-form content</h2>
<p>Browser-based submission of content types other than form are supported by
using form fields named <code>_content</code> and <code>_content_type</code>:</p>
<p>For example, given the following form:</p>
<pre><code>&lt;form action="/news-items/5" method="PUT"&gt;
&lt;input type="hidden" name="_content_type" value="application/json"&gt;
&lt;input name="_content" value="{'count': 1}"&gt;
&lt;/form&gt;
</code></pre>
<p><code>request.content_type</code> would return <code>"application/json"</code>, and
<code>request.stream</code> would return <code>"{'count': 1}"</code></p>
<h2 id="url-based-accept-headers">URL based accept headers</h2>
<p>REST framework can take <code>?accept=application/json</code> style URL parameters,
which allow the <code>Accept</code> header to be overridden.</p>
<p>This can be useful for testing the API from a web browser, where you don't
have any control over what is sent in the <code>Accept</code> header.</p>
<p>Note that prior to 3.3.0, this support was server-side rather than javascript based. The method overloading style (as used in <a href="http://guides.rubyonrails.org/form_helpers.html#how-do-forms-with-put-or-delete-methods-work">Ruby on Rails</a>) is no longer supported due to subtle issues that it introduces in request parsing.</p>
<h2 id="browser-based-submission-of-non-form-content">Browser based submission of non-form content</h2>
<p>Browser-based submission of content types such as JSON are supported by the <a href="https://github.com/tomchristie/ajax-form">AJAX form library</a>, using form fields with <code>data-override='content-type'</code> and <code>data-override='content'</code> attributes.</p>
<p>For example:</p>
<pre><code> &lt;form action="/"&gt;
&lt;input data-override='content-type' value='application/json' type='hidden'/&gt;
&lt;textarea data-override='content'&gt;{}&lt;/textarea&gt;
&lt;input type="submit"/&gt;
&lt;/form&gt;
</code></pre>
<p>Note that prior to 3.3.0, this support was server-side rather than javascript based.</p>
<h2 id="url-based-format-suffixes">URL based format suffixes</h2>
<p>REST framework can take <code>?format=json</code> style URL parameters, which can be a
useful shortcut for determining which content type should be returned from
the view.</p>
<p>This is a more concise than using the <code>accept</code> override, but it also gives
you less control. (For example you can't specify any media type parameters)</p>
<p>This behavior is controlled using the <code>URL_FORMAT_OVERRIDE</code> setting.</p>
<h2 id="http-header-based-method-overriding">HTTP header based method overriding</h2>
<p>Prior to version 3.3.0 the semi extension header <code>X-HTTP-Method-Override</code> was supported for overriding the request method. This behavior is no longer in core, but can be adding if needed using middleware.</p>
<p>For example:</p>
<pre><code>METHOD_OVERRIDE_HEADER = 'HTTP_X_HTTP_METHOD_OVERRIDE'
class MethodOverrideMiddleware(object):
def process_view(self, request, callback, callback_args, callback_kwargs):
if request.method != 'POST':
return
if METHOD_OVERRIDE_HEADER not in request.META:
return
request.method = request.META[METHOD_OVERRIDE_HEADER]
</code></pre>
<h2 id="url-based-accept-headers">URL based accept headers</h2>
<p>Until version 3.3.0 REST framework included built-in support for <code>?accept=application/json</code> style URL parameters, which would allow the <code>Accept</code> header to be overridden.</p>
<p>Since the introduction of the content negotiation API this behavior is no longer included in core, but may be added using a custom content negotiation class, if needed.</p>
<p>For example:</p>
<pre><code>class AcceptQueryParamOverride()
def get_accept_list(self, request):
header = request.META.get('HTTP_ACCEPT', '*/*')
header = request.query_params.get('_accept', header)
return [token.strip() for token in header.split(',')]
</code></pre>
<h2 id="doesnt-html5-support-put-and-delete-forms">Doesn't HTML5 support PUT and DELETE forms?</h2>
<p>Nope. It was at one point intended to support <code>PUT</code> and <code>DELETE</code> forms, but
was later <a href="http://www.w3.org/TR/html5-diff/#changes-2010-06-24">dropped from the spec</a>. There remains
@ -436,7 +450,7 @@ as well as how to support content types other than form-encoded data.</p>
</div> <!--/.wrapper -->
<footer class="span12">
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.</a>
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.
</p>
</footer>

10
topics/contributing/index.html
View File

@ -245,6 +245,10 @@
<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>
@ -281,6 +285,10 @@
<a href="../3.2-announcement/">3.2 Announcement</a>
</li>
<li >
<a href="../3.3-announcement/">3.3 Announcement</a>
</li>
<li >
<a href="../kickstarter-announcement/">Kickstarter Announcement</a>
</li>
@ -549,7 +557,7 @@ More text...
</div> <!--/.wrapper -->
<footer class="span12">
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.</a>
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.
</p>
</footer>

10
topics/documenting-your-api/index.html
View File

@ -245,6 +245,10 @@
<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>
@ -281,6 +285,10 @@
<a href="../3.2-announcement/">3.2 Announcement</a>
</li>
<li >
<a href="../3.3-announcement/">3.3 Announcement</a>
</li>
<li >
<a href="../kickstarter-announcement/">Kickstarter Announcement</a>
</li>
@ -432,7 +440,7 @@
</div> <!--/.wrapper -->
<footer class="span12">
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.</a>
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.
</p>
</footer>

729
topics/funding/index.html Normal file
View File

@ -0,0 +1,729 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta charset="utf-8">
<title>Funding - 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/funding/" />
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="description" content="Django, API, REST, Funding">
<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>
span.fusion-wrap a {
display: block;
margin-top: 10px;
color: black;
}
a.fusion-poweredby {
display: block;
margin-top: 10px;
}
@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="../release-notes/">
Next <i class="icon-arrow-right icon-white"></i>
</a>
<a class="repo-link btn btn-inverse btn-small " rel="next" href="../kickstarter-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>
</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/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="../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-resources/">Third Party 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="../3.0-announcement/">3.0 Announcement</a>
</li>
<li >
<a href="../3.1-announcement/">3.1 Announcement</a>
</li>
<li >
<a href="../3.2-announcement/">3.2 Announcement</a>
</li>
<li >
<a href="../3.3-announcement/">3.3 Announcement</a>
</li>
<li >
<a href="../kickstarter-announcement/">Kickstarter Announcement</a>
</li>
<li class="active" >
<a href="./">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">&times;</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="#funding">Funding</a>
</li>
<li>
<a href="#making-the-business-case">Making the business case</a>
</li>
<li>
<a href="#individual-plan">Individual plan</a>
</li>
<li>
<a href="#corporate-plans">Corporate plans</a>
</li>
<li>
<a href="#roadmap">Roadmap</a>
</li>
</ul>
</div>
</div>
<div id="main-content" class="span9">
<script>
// Imperfect, but easier to fit in with the existing docs build.
// Hyperlinks should point directly to the "fund." subdomain, but this'll
// handle the nav bar links without requiring any docs build changes for the moment.
if (window.location.hostname == "www.django-rest-framework.org") {
window.location.replace("https://fund.django-rest-framework.org/topics/funding/");
}
</script>
<style>
.chart {
background-color: #e3e3e3;
background: -webkit-linear-gradient(top, #fff 0, #e3e3e3 100%);
border: 1px solid #E6E6E6;
border-radius: 5px;
box-shadow: 0px 0px 2px 0px rgba(181, 181, 181, 0.3);
padding: 40px 0px 5px;
position: relative;
text-align: center;
width: 97%;
min-height: 255px;
position: relative;
top: 37px;
margin-bottom: 20px
}
.quantity {
text-align: center
}
.dollar {
font-size: 19px;
position: relative;
top: -18px;
}
.price {
font-size: 49px;
}
.period {
font-size: 17px;
position: relative;
top: -8px;
margin-left: 4px;
}
.plan-name {
text-align: center;
font-size: 20px;
font-weight: 400;
color: #777;
border-bottom: 1px solid #d5d5d5;
padding-bottom: 15px;
width: 90%;
margin: 0 auto;
margin-top: 8px;
}
.specs {
margin-top: 20px;
}
.specs.startup {
margin-bottom: 93px
}
.spec {
font-size: 15px;
color: #474747;
text-align: center;
font-weight: 300;
margin-bottom: 13px;
}
.variable {
color: #1FBEE7;
font-weight: 400;
}
form.signup {
margin-top: 35px
}
.clear-promo {
padding-top: 30px
}
#main-content h1:first-of-type {
margin: 0 0 50px;
font-size: 60px;
font-weight: 200;
text-align: center
}
#main-content {
padding-top: 10px; line-height: 23px
}
#main-content li {
line-height: 23px
}
</style>
<h1 id="funding">Funding</h1>
<p>If you use REST framework commercially we strongly encourage you to invest in its continued development by signing up for a paid plan.</p>
<p><strong>We believe that collaboratively funded software can offer outstanding returns on investment, by allowing users and clients to collectively share the cost of development.</strong></p>
<p>Signing up for a paid plan will:</p>
<ul>
<li>Directly contribute to faster releases, more features and higher quality software.</li>
<li>Allow more time to be invested in documentation, issue triage and community support.</li>
<li>Safeguard the future development of REST framework.</li>
</ul>
<p>REST framework will always be open source and permissively licensed, but we firmly believe it is in the commercial best-interest for users of the project to fund its ongoing development.</p>
<hr />
<h2 id="making-the-business-case">Making the business case</h2>
<p>Our successful Kickstarter campaign demonstrates the cost-reward ratio of shared development funding.</p>
<p>With <em>typical corporate fundings of just £100-£1000 per organization</em> we successfully delivered:</p>
<ul>
<li>The comprehensive 3.0 serializer redesign.</li>
<li>Substantial improvements to the Browsable API.</li>
<li>The admin interface.</li>
<li>A new pagination API including offset/limit and cursor pagination implementations, plus on-page controls.</li>
<li>A versioning API, including URL-based and header-based versioning schemes.</li>
<li>Support for customizable exception handling.</li>
<li>Support for Django's PostgreSQL HStoreField, ArrayField and JSONField.</li>
<li>Templated HTML form support, including HTML forms with nested list and objects.</li>
<li>Internationalization support for API responses, currently with 27 languages.</li>
<li>The metadata APIs for handling <code>OPTIONS</code> requests and schema endpoints.</li>
<li>Numerous minor improvements and better quality throughout the codebase.</li>
<li>Ongoing triage and community support, closing over 1600 tickets.</li>
</ul>
<p>This incredible level of return on investment is <em>only possible through collaboratively funded models</em>, which is why we believe that supporting our paid plans is in everyone's best interest.</p>
<hr />
<h2 id="individual-plan">Individual plan</h2>
<p>This subscription is recommended for freelancers and other individuals with an interest in seeing REST framework continue to&nbsp;improve.</p>
<p>If you are using REST framework as an full-time employee, consider recommending that your company takes out a <a href="#corporate-plans">corporate&nbsp;plan</a>.</p>
<div class="pricing">
<div class="span4">
<div class="chart first">
<div class="quantity">
<span class="dollar">$</span>
<span class="price">15</span>
<span class="period">/month</span>
</div>
<div class="plan-name">Individual</div>
<div class="specs">
<div class="spec">
Support ongoing development
</div>
<div class="spec">
Credited on the site
</div>
</div>
<form class="signup" action="/signup/individual/" method="POST">
<script
src="https://checkout.stripe.com/checkout.js" class="stripe-button"
data-key="{{ stripe_public }}"
data-amount="1500"
data-name="Django REST framework"
data-description="Individual"
data-currency="usd"
data-allow-remember-me=false
data-billing-address=true
data-label='Sign up'
data-panel-label='Sign up - {% verbatim %}{{amount}}{% endverbatim %}/mo'>
</script>
</form>
</div>
</div>
</div>
<div style="clear: both; padding-top: 50px"></div>
<p><em>Billing is monthly and you can cancel at any time.</em></p>
<hr />
<h2 id="corporate-plans">Corporate plans</h2>
<p>These subscriptions are recommended for companies and organizations using REST framework either publicly or privately.</p>
<p>In exchange for funding you'll also receive advertising space on our site, allowing you to <strong>promote your company or product to many tens of thousands of developers worldwide</strong>.</p>
<p>Our professional and premium plans also include <strong>priority support</strong>. At any time your engineers can escalate an issue or discussion group thread, and we'll ensure it gets a guaranteed response within the next working day.</p>
<div class="pricing">
<div class="span4">
<div class="chart first">
<div class="quantity">
<span class="dollar">$</span>
<span class="price">50</span>
<span class="period">/month</span>
</div>
<div class="plan-name">Basic</div>
<div class="specs startup">
<div class="spec">
Support ongoing development
</div>
<div class="spec">
<span class="variable">Funding page</span> ad placement
</div>
</div>
<form class="signup" action="/signup/startup/" method="POST">
<script
src="https://checkout.stripe.com/checkout.js" class="stripe-button"
data-key="{{ stripe_public }}"
data-amount="5000"
data-name="Django REST framework"
data-description="Basic"
data-currency="usd"
data-allow-remember-me=false
data-billing-address=true
data-label='Sign up'
data-panel-label='Sign up - {% verbatim %}{{amount}}{% endverbatim %}/mo'>
</script>
</form>
</div>
</div>
<div class="span4">
<div class="chart">
<div class="quantity">
<span class="dollar">$</span>
<span class="price">250</span>
<span class="period">/month</span>
</div>
<div class="plan-name">Professional</div>
<div class="specs">
<div class="spec">
Add a <span class="variable">half day per&nbsp;month</span> development time to the project
</div>
<div class="spec">
<span class="variable">Homepage</span> ad placement
</div>
<div class="spec">
<span class="variable">Priority support</span> for your engineers
</div>
</div>
<form class="signup" action="/signup/professional/" method="POST">
<script
src="https://checkout.stripe.com/checkout.js" class="stripe-button"
data-key="{{ stripe_public }}"
data-amount="25000"
data-name="Django REST framework"
data-description="Professional"
data-currency="usd"
data-allow-remember-me=false
data-billing-address=true
data-label='Sign up'
data-panel-label='Sign up - {% verbatim %}{{amount}}{% endverbatim %}/mo'>
</script>
</form>
</div>
</div>
<div class="span4">
<div class="chart last">
<div class="quantity">
<span class="dollar">$</span>
<span class="price">500</span>
<span class="period">/month</span>
</div>
<div class="plan-name">Premium</div>
<div class="specs">
<div class="spec">
Add <span class="variable">one full day per&nbsp;month</span> development time to the project
</div>
<div class="spec">
<span class="variable">Full site</span> ad placement
</div>
<div class="spec">
<span class="variable">Priority support</span> for your engineers
</div>
</div>
<form class="signup" action="/signup/premium/" method="POST">
<script
src="https://checkout.stripe.com/checkout.js" class="stripe-button"
data-key="{{ stripe_public }}"
data-amount="50000"
data-name="Django REST framework"
data-description="Premium"
data-currency="usd"
data-allow-remember-me=false
data-billing-address=true
data-label='Sign up'
data-panel-label='Sign up - {% verbatim %}{{amount}}{% endverbatim %}/mo'>
</script>
</form>
</div>
</div>
</div>
<div style="clear: both; padding-top: 50px"></div>
<p><em>Billing is monthly and you can cancel at any time.</em></p>
<p>Once you've signed up we'll contact you via email and arrange your ad placements on the site.</p>
<p>For further enquires please contact <a href=mailto:tom@tomchristie.com>tom@tomchristie.com</a>.</p>
<hr />
<h2 id="roadmap">Roadmap</h2>
<p>Although we're incredibly proud of REST framework in its current state we believe there is still huge scope for improvement. What we're aiming for here is a <em>highly polished, rock solid product</em>. This needs to backed up with impeccable documentation and a great third party ecosystem.</p>
<p>The roadmap below is a broad indication of just some of the ongoing and future work we believe is important to REST framework.</p>
<ul>
<li>Increasing our "bus factor" through documented organizational process &amp; safeguards.</li>
<li>More time towards testing and hardening releases, with only gradual, well-documented deprecations.</li>
<li>A formal policy on security backports for non-current releases.</li>
<li>Continuing triage &amp; community support.</li>
<li>Improved project documentation, including versioned &amp; internationalized docs.</li>
<li>Improved third party package visibility.</li>
<li>Refining the admin interface, ensuring it has a fully customizable API and making it suitable as end-user facing application.</li>
<li>Cleaning up internal complexities including the <code>BrowsableAPIRenderer</code> and <code>Request</code> object.</li>
<li>Support for alternative backends such as SQLAlchemy.</li>
<li>Support for non-database backed services.</li>
<li>HTTP Caching API &amp; support for conditional database lookups.</li>
<li>Benchmarking and performance improvements.</li>
<li>In depth documentation on advanced usage and best practices.</li>
<li>Documentation &amp; support for integration with realtime systems.</li>
<li>Hypermedia support and client libraries.</li>
<li>Support for JSON schema as endpoints or <code>OPTIONS</code> responses.</li>
<li>API metric tools.</li>
<li>Debug &amp; logging tools.</li>
<li>Third party GraphQL support.</li>
</ul>
<p>By taking out a paid plan you'll be directly contributing towards making these features happen.</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>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>

640
topics/html-and-forms/index.html Normal file
View File

@ -0,0 +1,640 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta charset="utf-8">
<title>HTML & Forms - 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/html-and-forms/" />
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="description" content="Django, API, REST, HTML & Forms">
<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>
span.fusion-wrap a {
display: block;
margin-top: 10px;
color: black;
}
a.fusion-poweredby {
display: block;
margin-top: 10px;
}
@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="../browser-enhancements/">
Next <i class="icon-arrow-right icon-white"></i>
</a>
<a class="repo-link btn btn-inverse btn-small " rel="next" href="../ajax-csrf-cors/">
<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>
</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/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="../internationalization/">Internationalization</a>
</li>
<li >
<a href="../ajax-csrf-cors/">AJAX, CSRF & CORS</a>
</li>
<li class="active" >
<a href="./">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-resources/">Third Party 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="../3.0-announcement/">3.0 Announcement</a>
</li>
<li >
<a href="../3.1-announcement/">3.1 Announcement</a>
</li>
<li >
<a href="../3.2-announcement/">3.2 Announcement</a>
</li>
<li >
<a href="../3.3-announcement/">3.3 Announcement</a>
</li>
<li >
<a href="../kickstarter-announcement/">Kickstarter Announcement</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">&times;</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="#html-forms">HTML Forms</a>
</li>
<li>
<a href="#rendering-html">Rendering HTML</a>
</li>
<li>
<a href="#rendering-forms">Rendering Forms</a>
</li>
<li>
<a href="#field-styles">Field styles</a>
</li>
</ul>
</div>
</div>
<div id="main-content" class="span9">
<h1 id="html-forms">HTML &amp; Forms</h1>
<p>REST framework is suitable for returning both API style responses, and regular HTML pages. Additionally, serializers can used as HTML forms and rendered in templates.</p>
<h2 id="rendering-html">Rendering HTML</h2>
<p>In order to return HTML responses you'll need to either <code>TemplateHTMLRenderer</code>, or <code>StaticHTMLRenderer</code>.</p>
<p>The <code>TemplateHTMLRenderer</code> class expects the response to contain a dictionary of context data, and renders an HTML page based on a template that must be specified either in the view or on the response.</p>
<p>The <code>StaticHTMLRender</code> class expects the response to contain a string of the pre-rendered HTML content.</p>
<p>Because static HTML pages typically have different behavior from API responses you'll probably need to write any HTML views explicitly, rather than relying on the built-in generic views.</p>
<p>Here's an example of a view that returns a list of "Profile" instances, rendered in an HTML template:</p>
<p><strong>views.py</strong>:</p>
<pre><code>from my_project.example.models import Profile
from rest_framework.renderers import TemplateHTMLRenderer
from rest_framework.views import APIView
class ProfileList(APIView):
renderer_classes = [TemplateHTMLRenderer]
template_name = 'profile_list.html'
def get(self, request):
queryset = Profile.objects.all()
return Response({'profiles': queryset})
</code></pre>
<p><strong>profile_list.html</strong>:</p>
<pre><code>&lt;html&gt;&lt;body&gt;
&lt;h1&gt;Profiles&lt;/h1&gt;
&lt;ul&gt;
{% for profile in profiles %}
&lt;li&gt;{{ profile.name }}&lt;/li&gt;
{% endfor %}
&lt;/ul&gt;
&lt;/body&gt;&lt;/html&gt;
</code></pre>
<h2 id="rendering-forms">Rendering Forms</h2>
<p>Serializers may be rendered as forms by using the <code>render_form</code> template tag, and including the serializer instance as context to the template.</p>
<p>The following view demonstrates an example of using a serializer in a template for viewing and updating a model instance:</p>
<p><strong>views.py</strong>:</p>
<pre><code>from django.shortcuts import get_object_or_404
from my_project.example.models import Profile
from rest_framework.renderers import TemplateHTMLRenderer
from rest_framework.views import APIView
class ProfileDetail(APIView):
renderer_classes = [TemplateHTMLRenderer]
template_name = 'profile_detail.html'
def get(self, request, pk):
profile = get_object_or_404(Profile, pk=pk)
serializer = ProfileSerializer(profile)
return Response({'serializer': serializer, 'profile': profile})
def post(self, request, pk):
profile = get_object_or_404(Profile, pk=pk)
serializer = ProfileSerializer(profile)
if not serializer.is_valid():
return Response({'serializer': serializer, 'profile': profile})
return redirect('profile-list')
</code></pre>
<p><strong>profile_detail.html</strong>:</p>
<pre><code>{% load rest_framework %}
&lt;html&gt;&lt;body&gt;
&lt;h1&gt;Profile - {{ profile.name }}&lt;/h1&gt;
&lt;form action="{% url 'profile-detail' pk=profile.pk '%}" method="POST"&gt;
{% csrf_token %}
{% render_form serializer %}
&lt;input type="submit" value="Save"&gt;
&lt;/form&gt;
&lt;/body&gt;&lt;/html&gt;
</code></pre>
<h3 id="using-template-packs">Using template packs</h3>
<p>The <code>render_form</code> tag takes an optional <code>template_pack</code> argument, that specifies which template directory should be used for rendering the form and form fields.</p>
<p>REST framework includes three built-in template packs, all based on Bootstrap 3. The built-in styles are <code>horizontal</code>, <code>vertical</code>, and <code>inline</code>. The default style is <code>horizontal</code>. To use any of these template packs you'll want to also include the Bootstrap 3 CSS.</p>
<p>The following HTML will link to a CDN hosted version of the Bootstrap 3 CSS:</p>
<pre><code>&lt;head&gt;
…
&lt;link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.5/css/bootstrap.min.css"&gt;
&lt;/head&gt;
</code></pre>
<p>Third party packages may include alternate template packs, by bundling a template directory containing the necessary form and field templates.</p>
<p>Let's take a look at how to render each of the three available template packs. For these examples we'll use a single serializer class to present a "Login" form.</p>
<pre><code>class LoginSerializer(serializers.Serializer):
email = serializers.EmailField(
max_length=100,
style={'placeholder': 'Email'}
)
password = serializers.CharField(
max_length=100,
style={'input_type': 'password', 'placeholder': 'Password'}
)
remember_me = serializers.BooleanField()
</code></pre>
<hr />
<h4 id="rest_frameworkvertical"><code>rest_framework/vertical</code></h4>
<p>Presents form labels above their corresponding control inputs, using the standard Bootstrap layout.</p>
<p><em>This is the default template pack.</em></p>
<pre><code>{% load rest_framework %}
...
&lt;form action="{% url 'login' %}" method="post" novalidate&gt;
{% csrf_token %}
{% render_form serializer template_pack='rest_framework/vertical' %}
&lt;button type="submit" class="btn btn-default"&gt;Sign in&lt;/button&gt;
&lt;/form&gt;
</code></pre>
<p><img alt="Vertical form example" src="../../img/vertical.png" /></p>
<hr />
<h4 id="rest_frameworkhorizontal"><code>rest_framework/horizontal</code></h4>
<p>Presents labels and controls alongside each other, using a 2/10 column split.</p>
<p><em>This is the form style used in the browsable API and admin renderers.</em></p>
<pre><code>{% load rest_framework %}
...
&lt;form class="form-horizontal" action="{% url 'login' %}" method="post" novalidate&gt;
{% csrf_token %}
{% render_form serializer %}
&lt;div class="form-group"&gt;
&lt;div class="col-sm-offset-2 col-sm-10"&gt;
&lt;button type="submit" class="btn btn-default"&gt;Sign in&lt;/button&gt;
&lt;/div&gt;
&lt;/div&gt;
&lt;/form&gt;
</code></pre>
<p><img alt="Horizontal form example" src="../../img/horizontal.png" /></p>
<hr />
<h4 id="rest_frameworkinline"><code>rest_framework/inline</code></h4>
<p>A compact form style that presents all the controls inline.</p>
<pre><code>{% load rest_framework %}
...
&lt;form class="form-inline" action="{% url 'login' %}" method="post" novalidate&gt;
{% csrf_token %}
{% render_form serializer template_pack='rest_framework/inline' %}
&lt;button type="submit" class="btn btn-default"&gt;Sign in&lt;/button&gt;
&lt;/form&gt;
</code></pre>
<p><img alt="Inline form example" src="../../img/inline.png" /></p>
<h2 id="field-styles">Field styles</h2>
<p>Serializer fields can have their rendering style customized by using the <code>style</code> keyword argument. This argument is a dictionary of options that control the template and layout used.</p>
<p>The most common way to customize the field style is to use the <code>base_template</code> style keyword argument to select which template in the template pack should be use.</p>
<p>For example, to render a <code>CharField</code> as an HTML textarea rather than the default HTML input, you would use something like this:</p>
<pre><code>details = serializers.CharField(
max_length=1000,
style={'base_template': 'textarea.html'}
)
</code></pre>
<p>If you instead want a field to be rendered using a custom template that is <em>not part of an included template pack</em>, you can instead use the <code>template</code> style option, to fully specify a template name:</p>
<pre><code>details = serializers.CharField(
max_length=1000,
style={'template': 'my-field-templates/custom-input.html'}
)
</code></pre>
<p>Field templates can also use additional style properties, depending on their type. For example, the <code>textarea.html</code> template also accepts a <code>rows</code> property that can be used to affect the sizing of the control.</p>
<pre><code>details = serializers.CharField(
max_length=1000,
style={'base_template': 'textarea.html', 'rows': 10}
)
</code></pre>
<p>The complete list of <code>base_template</code> options and their associated style options is listed below.</p>
<table>
<thead>
<tr>
<th>base_template</th>
<th>Valid field types</th>
<th>Additional style options</th>
</tr>
</thead>
<tbody>
<tr>
<td>input.html</td>
<td>Any string, numeric or date/time field</td>
<td>input_type, placeholder, hide_label</td>
</tr>
<tr>
<td>textarea.html</td>
<td><code>CharField</code></td>
<td>rows, placeholder, hide_label</td>
</tr>
<tr>
<td>select.html</td>
<td><code>ChoiceField</code> or relational field types</td>
<td>hide_label</td>
</tr>
<tr>
<td>radio.html</td>
<td><code>ChoiceField</code> or relational field types</td>
<td>inline, hide_label</td>
</tr>
<tr>
<td>select_multiple.html</td>
<td><code>MultipleChoiceField</code> or relational fields with <code>many=True</code></td>
<td>hide_label</td>
</tr>
<tr>
<td>checkbox_multiple.html</td>
<td><code>MultipleChoiceField</code> or relational fields with <code>many=True</code></td>
<td>inline, hide_label</td>
</tr>
<tr>
<td>checkbox.html</td>
<td><code>BooleanField</code></td>
<td>hide_label</td>
</tr>
<tr>
<td>fieldset.html</td>
<td>Nested serializer</td>
<td>hide_label</td>
</tr>
<tr>
<td>list_fieldset.html</td>
<td><code>ListField</code> or nested serializer with <code>many=True</code></td>
<td>hide_label</td>
</tr>
</tbody>
</table>
</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>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>

10
topics/internationalization/index.html
View File

@ -245,6 +245,10 @@
<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>
@ -281,6 +285,10 @@
<a href="../3.2-announcement/">3.2 Announcement</a>
</li>
<li >
<a href="../3.3-announcement/">3.3 Announcement</a>
</li>
<li >
<a href="../kickstarter-announcement/">Kickstarter Announcement</a>
</li>
@ -460,7 +468,7 @@ available for Django to use. You should see a message like <code>processing file
</div> <!--/.wrapper -->
<footer class="span12">
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.</a>
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.
</p>
</footer>

12
topics/kickstarter-announcement/index.html
View File

@ -64,7 +64,7 @@
<a class="repo-link btn btn-inverse btn-small " rel="prev" href="../release-notes/">
Next <i class="icon-arrow-right icon-white"></i>
</a>
<a class="repo-link btn btn-inverse btn-small " rel="next" href="../3.2-announcement/">
<a class="repo-link btn btn-inverse btn-small " rel="next" href="../3.3-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>
@ -245,6 +245,10 @@
<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>
@ -281,6 +285,10 @@
<a href="../3.2-announcement/">3.2 Announcement</a>
</li>
<li >
<a href="../3.3-announcement/">3.3 Announcement</a>
</li>
<li class="active" >
<a href="./">Kickstarter Announcement</a>
</li>
@ -500,7 +508,7 @@
</div> <!--/.wrapper -->
<footer class="span12">
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.</a>
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.
</p>
</footer>

10
topics/project-management/index.html
View File

@ -245,6 +245,10 @@
<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>
@ -281,6 +285,10 @@
<a href="../3.2-announcement/">3.2 Announcement</a>
</li>
<li >
<a href="../3.3-announcement/">3.3 Announcement</a>
</li>
<li >
<a href="../kickstarter-announcement/">Kickstarter Announcement</a>
</li>
@ -540,7 +548,7 @@ django-admin.py compilemessages
</div> <!--/.wrapper -->
<footer class="span12">
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.</a>
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.
</p>
</footer>

38
topics/release-notes/index.html
View File

@ -245,6 +245,10 @@
<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>
@ -281,6 +285,10 @@
<a href="../3.2-announcement/">3.2 Announcement</a>
</li>
<li >
<a href="../3.3-announcement/">3.3 Announcement</a>
</li>
<li >
<a href="../kickstarter-announcement/">Kickstarter Announcement</a>
</li>
@ -349,6 +357,10 @@
<a href="#upgrading">Upgrading</a>
</li>
<li>
<a href="#33x-series">3.3.x series</a>
</li>
<li>
<a href="#32x-series">3.2.x series</a>
</li>
@ -405,16 +417,32 @@
<pre><code>pip freeze | grep djangorestframework
</code></pre>
<hr />
<h2 id="33x-series">3.3.x series</h2>
<h3 id="330">3.3.0</h3>
<p><strong>Date</strong>: <a href="https://github.com/tomchristie/django-rest-framework/issues?q=milestone%3A%223.3.0+Release%22">28th October 2015</a>.</p>
<ul>
<li>HTML controls for filters. (<a href="https://github.com/tomchristie/django-rest-framework/issues/3315">#3315</a>)</li>
<li>Forms API. (<a href="https://github.com/tomchristie/django-rest-framework/issues/3475">#3475</a>)</li>
<li>AJAX browsable API. (<a href="https://github.com/tomchristie/django-rest-framework/issues/3410">#3410</a>)</li>
<li>Added JSONField. (<a href="https://github.com/tomchristie/django-rest-framework/issues/3454">#3454</a>)</li>
<li>Correctly map <code>to_field</code> when creating <code>ModelSerializer</code> relational fields. (<a href="https://github.com/tomchristie/django-rest-framework/issues/3526">#3526</a>)</li>
<li>Include keyword arguments when mapping <code>FilePathField</code> to a serializer field. (<a href="https://github.com/tomchristie/django-rest-framework/issues/3536">#3536</a>)</li>
<li>Map appropriate model <code>error_messages</code> on <code>ModelSerializer</code> uniqueness constraints. (<a href="https://github.com/tomchristie/django-rest-framework/issues/3435">#3435</a>)</li>
<li>Include <code>max_length</code> constraint for <code>ModelSerializer</code> fields mapped from TextField. (<a href="https://github.com/tomchristie/django-rest-framework/issues/3509">#3509</a>)</li>
<li>Added support for Django 1.9. (<a href="https://github.com/tomchristie/django-rest-framework/issues/3450">#3450</a>, <a href="https://github.com/tomchristie/django-rest-framework/issues/3525">#3525</a>)</li>
<li>Removed support for Django 1.5 &amp; 1.6. (<a href="https://github.com/tomchristie/django-rest-framework/issues/3421">#3421</a>, <a href="https://github.com/tomchristie/django-rest-framework/issues/3429">#3429</a>)</li>
<li>Removed 'south' migrations. (<a href="https://github.com/tomchristie/django-rest-framework/issues/3495">#3495</a>)</li>
</ul>
<h2 id="32x-series">3.2.x series</h2>
<h3 id="325">3.2.5</h3>
<p><strong>Date</strong>: <a href="https://github.com/tomchristie/django-rest-framework/issues?q=milestone%3A%223.2.5+Release%22">27th October 2015</a>.</p>
<ul>
<li>Escape <code>username</code> in optional logout tag.</li>
<li>Escape <code>username</code> in optional logout tag. (<a href="https://github.com/tomchristie/django-rest-framework/issues/3550">#3550</a>)</li>
</ul>
<h3 id="324">3.2.4</h3>
<p><strong>Date</strong>: <a href="https://github.com/tomchristie/django-rest-framework/issues?q=milestone%3A%223.2.4+Release%22">21th September 2015</a>.</p>
<ul>
<li>Don't error on missing <code>ViewSet.search_fields</code> attribute.(<a href="https://github.com/tomchristie/django-rest-framework/issues/3324">#3324</a>, <a href="https://github.com/tomchristie/django-rest-framework/issues/3323">#3323</a>)</li>
<li>Don't error on missing <code>ViewSet.search_fields</code> attribute. (<a href="https://github.com/tomchristie/django-rest-framework/issues/3324">#3324</a>, <a href="https://github.com/tomchristie/django-rest-framework/issues/3323">#3323</a>)</li>
<li>Fix <code>allow_empty</code> not working on serializers with <code>many=True</code>. (<a href="https://github.com/tomchristie/django-rest-framework/issues/3361">#3361</a>, <a href="https://github.com/tomchristie/django-rest-framework/issues/3364">#3364</a>)</li>
<li>Let <code>DurationField</code> accepts integers. (<a href="https://github.com/tomchristie/django-rest-framework/issues/3359">#3359</a>)</li>
<li>Multi-level dictionaries not supported in multipart requests. (<a href="https://github.com/tomchristie/django-rest-framework/issues/3314">#3314</a>)</li>
@ -645,6 +673,10 @@
<!-- 3.2.3 -->
<!-- 3.2.4 -->
<!-- 3.2.5 -->
<!-- 3.3.0 -->
</div> <!--/span-->
@ -655,7 +687,7 @@
</div> <!--/.wrapper -->
<footer class="span12">
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.</a>
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.
</p>
</footer>

10
topics/rest-hypermedia-hateoas/index.html
View File

@ -245,6 +245,10 @@
<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>
@ -281,6 +285,10 @@
<a href="../3.2-announcement/">3.2 Announcement</a>
</li>
<li >
<a href="../3.3-announcement/">3.3 Announcement</a>
</li>
<li >
<a href="../kickstarter-announcement/">Kickstarter Announcement</a>
</li>
@ -396,7 +404,7 @@ the Design of Network-based Software Architectures</a>.</li>
</div> <!--/.wrapper -->
<footer class="span12">
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.</a>
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.
</p>
</footer>

12
topics/third-party-resources/index.html
View File

@ -245,6 +245,10 @@
<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>
@ -281,6 +285,10 @@
<a href="../3.2-announcement/">3.2 Announcement</a>
</li>
<li >
<a href="../3.3-announcement/">3.3 Announcement</a>
</li>
<li >
<a href="../kickstarter-announcement/">Kickstarter Announcement</a>
</li>
@ -540,6 +548,7 @@ You probably want to also tag the version now:
</ul>
<h3 id="misc">Misc</h3>
<ul>
<li><a href="https://github.com/agconti/cookiecutter-django-rest">cookiecutter-django-rest</a> - A cookiecutter template that takes care of the setup and configuration so you can focus on making your REST apis awesome.</li>
<li><a href="https://github.com/fredkingham/django_rest_model_hyperlink_serializers_project">djangorestrelationalhyperlink</a> - A hyperlinked serialiser that can can be used to alter relationships via hyperlinks, but otherwise like a hyperlink model serializer.</li>
<li><a href="https://github.com/marcgibbons/django-rest-swagger">django-rest-swagger</a> - An API documentation generator for Swagger UI.</li>
<li><a href="https://github.com/eofs/django-rest-framework-proxy">django-rest-framework-proxy</a> - Proxy to redirect incoming request to another API server.</li>
@ -549,6 +558,7 @@ You probably want to also tag the version now:
<li><a href="https://github.com/WGBH/django-versatileimagefield">django-versatileimagefield</a> - Provides a drop-in replacement for Django's stock <code>ImageField</code> that makes it easy to serve images in multiple sizes/renditions from a single field. For DRF-specific implementation docs, <a href="http://django-versatileimagefield.readthedocs.org/en/latest/drf_integration.html">click here</a>.</li>
<li><a href="https://github.com/aschn/drf-tracking">drf-tracking</a> - Utilities to track requests to DRF API views.</li>
<li><a href="https://github.com/dealertrack/django-rest-framework-braces">django-rest-framework-braces</a> - Collection of utilities for working with Django Rest Framework. The most notable ones are <a href="https://django-rest-framework-braces.readthedocs.org/en/latest/overview.html#formserializer">FormSerializer</a> and <a href="https://django-rest-framework-braces.readthedocs.org/en/latest/overview.html#serializerform">SerializerForm</a>, which are adapters between DRF serializers and Django forms.</li>
<li><a href="http://drf-haystack.readthedocs.org/en/latest/">drf-haystack</a> - Haystack search for Django Rest Framework</li>
</ul>
<h2 id="other-resources">Other Resources</h2>
<h3 id="tutorials">Tutorials</h3>
@ -588,7 +598,7 @@ You probably want to also tag the version now:
</div> <!--/.wrapper -->
<footer class="span12">
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.</a>
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.
</p>
</footer>

10
tutorial/1-serialization/index.html
View File

@ -245,6 +245,10 @@
<a href="../../topics/ajax-csrf-cors/">AJAX, CSRF & CORS</a>
</li>
<li >
<a href="../../topics/html-and-forms/">HTML & Forms</a>
</li>
<li >
<a href="../../topics/browser-enhancements/">Browser Enhancements</a>
</li>
@ -281,6 +285,10 @@
<a href="../../topics/3.2-announcement/">3.2 Announcement</a>
</li>
<li >
<a href="../../topics/3.3-announcement/">3.3 Announcement</a>
</li>
<li >
<a href="../../topics/kickstarter-announcement/">Kickstarter Announcement</a>
</li>
@ -717,7 +725,7 @@ HTTP/1.1 200 OK
</div> <!--/.wrapper -->
<footer class="span12">
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.</a>
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.
</p>
</footer>

10
tutorial/2-requests-and-responses/index.html
View File

@ -245,6 +245,10 @@
<a href="../../topics/ajax-csrf-cors/">AJAX, CSRF & CORS</a>
</li>
<li >
<a href="../../topics/html-and-forms/">HTML & Forms</a>
</li>
<li >
<a href="../../topics/browser-enhancements/">Browser Enhancements</a>
</li>
@ -281,6 +285,10 @@
<a href="../../topics/3.2-announcement/">3.2 Announcement</a>
</li>
<li >
<a href="../../topics/3.3-announcement/">3.3 Announcement</a>
</li>
<li >
<a href="../../topics/kickstarter-announcement/">Kickstarter Announcement</a>
</li>
@ -556,7 +564,7 @@ http --json POST http://127.0.0.1:8000/snippets/ code="print 456"
</div> <!--/.wrapper -->
<footer class="span12">
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.</a>
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.
</p>
</footer>

10
tutorial/3-class-based-views/index.html
View File

@ -245,6 +245,10 @@
<a href="../../topics/ajax-csrf-cors/">AJAX, CSRF & CORS</a>
</li>
<li >
<a href="../../topics/html-and-forms/">HTML & Forms</a>
</li>
<li >
<a href="../../topics/browser-enhancements/">Browser Enhancements</a>
</li>
@ -281,6 +285,10 @@
<a href="../../topics/3.2-announcement/">3.2 Announcement</a>
</li>
<li >
<a href="../../topics/3.3-announcement/">3.3 Announcement</a>
</li>
<li >
<a href="../../topics/kickstarter-announcement/">Kickstarter Announcement</a>
</li>
@ -500,7 +508,7 @@ class SnippetDetail(generics.RetrieveUpdateDestroyAPIView):
</div> <!--/.wrapper -->
<footer class="span12">
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.</a>
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.
</p>
</footer>

10
tutorial/4-authentication-and-permissions/index.html
View File

@ -245,6 +245,10 @@
<a href="../../topics/ajax-csrf-cors/">AJAX, CSRF & CORS</a>
</li>
<li >
<a href="../../topics/html-and-forms/">HTML & Forms</a>
</li>
<li >
<a href="../../topics/browser-enhancements/">Browser Enhancements</a>
</li>
@ -281,6 +285,10 @@
<a href="../../topics/3.2-announcement/">3.2 Announcement</a>
</li>
<li >
<a href="../../topics/3.3-announcement/">3.3 Announcement</a>
</li>
<li >
<a href="../../topics/kickstarter-announcement/">Kickstarter Announcement</a>
</li>
@ -567,7 +575,7 @@ class IsOwnerOrReadOnly(permissions.BasePermission):
</div> <!--/.wrapper -->
<footer class="span12">
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.</a>
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.
</p>
</footer>

10
tutorial/5-relationships-and-hyperlinked-apis/index.html
View File

@ -245,6 +245,10 @@
<a href="../../topics/ajax-csrf-cors/">AJAX, CSRF & CORS</a>
</li>
<li >
<a href="../../topics/html-and-forms/">HTML & Forms</a>
</li>
<li >
<a href="../../topics/browser-enhancements/">Browser Enhancements</a>
</li>
@ -281,6 +285,10 @@
<a href="../../topics/3.2-announcement/">3.2 Announcement</a>
</li>
<li >
<a href="../../topics/3.3-announcement/">3.3 Announcement</a>
</li>
<li >
<a href="../../topics/kickstarter-announcement/">Kickstarter Announcement</a>
</li>
@ -514,7 +522,7 @@ urlpatterns += [
</div> <!--/.wrapper -->
<footer class="span12">
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.</a>
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.
</p>
</footer>

10
tutorial/6-viewsets-and-routers/index.html
View File

@ -245,6 +245,10 @@
<a href="../../topics/ajax-csrf-cors/">AJAX, CSRF & CORS</a>
</li>
<li >
<a href="../../topics/html-and-forms/">HTML & Forms</a>
</li>
<li >
<a href="../../topics/browser-enhancements/">Browser Enhancements</a>
</li>
@ -281,6 +285,10 @@
<a href="../../topics/3.2-announcement/">3.2 Announcement</a>
</li>
<li >
<a href="../../topics/3.3-announcement/">3.3 Announcement</a>
</li>
<li >
<a href="../../topics/kickstarter-announcement/">Kickstarter Announcement</a>
</li>
@ -501,7 +509,7 @@ urlpatterns = [
</div> <!--/.wrapper -->
<footer class="span12">
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.</a>
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.
</p>
</footer>

10
tutorial/quickstart/index.html
View File

@ -245,6 +245,10 @@
<a href="../../topics/ajax-csrf-cors/">AJAX, CSRF & CORS</a>
</li>
<li >
<a href="../../topics/html-and-forms/">HTML & Forms</a>
</li>
<li >
<a href="../../topics/browser-enhancements/">Browser Enhancements</a>
</li>
@ -281,6 +285,10 @@
<a href="../../topics/3.2-announcement/">3.2 Announcement</a>
</li>
<li >
<a href="../../topics/3.3-announcement/">3.3 Announcement</a>
</li>
<li >
<a href="../../topics/kickstarter-announcement/">Kickstarter Announcement</a>
</li>
@ -544,7 +552,7 @@ HTTP/1.1 200 OK
</div> <!--/.wrapper -->
<footer class="span12">
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.</a>
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.
</p>
</footer>