Skip to content

D
django-rest-framework
Commit e628d9eb by Tom Christie
Options

Update documentation

parent ccb2b8ff
Showing with 1520 additions and 3350 deletions
.DS_Store 0 → 100644
File added
api-guide/authentication/index.html
......@@ -189,6 +189,10 @@
</li>
<li >
<a href="../versioning">Versioning</a>
</li>
<li >
<a href="../content-negotiation">Content negotiation</a>
</li>
......@@ -232,6 +236,10 @@
</li>
<li >
<a href="../../topics/internationalization">Internationalization</a>
</li>
<li >
<a href="../../topics/ajax-csrf-cors">AJAX, CSRF & CORS</a>
</li>
......@@ -260,23 +268,11 @@
</li>
<li >
<a href="../../topics/rest-framework-2-announcement">2.0 Announcement</a>
</li>
<li >
<a href="../../topics/2.2-announcement">2.2 Announcement</a>
</li>
<li >
<a href="../../topics/2.3-announcement">2.3 Announcement</a>
</li>
<li >
<a href="../../topics/2.4-announcement">2.4 Announcement</a>
<a href="../../topics/3.0-announcement">3.0 Announcement</a>
</li>
<li >
<a href="../../topics/3.0-announcement">3.0 Announcement</a>
<a href="../../topics/3.1-announcement">3.1 Announcement</a>
</li>
<li >
......@@ -287,10 +283,6 @@
<a href="../../topics/release-notes">Release Notes</a>
</li>
<li >
<a href="../../topics/credits">Credits</a>
</li>
</ul>
</li>
......@@ -393,14 +385,6 @@
<a href="#sessionauthentication">SessionAuthentication</a>
</li>
<li>
<a href="#oauthauthentication">OAuthAuthentication</a>
</li>
<li>
<a href="#oauth2authentication">OAuth2Authentication</a>
</li>
......@@ -422,11 +406,15 @@
<li>
<a href="#digest-authentication">Digest Authentication</a>
<a href="#django-oauth-toolkit">Django OAuth Toolkit</a>
</li>
<li>
<a href="#django-oauth-toolkit">Django OAuth Toolkit</a>
<a href="#django-rest-framework-oauth">Django REST framework OAuth</a>
</li>
<li>
<a href="#digest-authentication">Digest Authentication</a>
</li>
<li>
......@@ -449,6 +437,10 @@
<a href="#djoser">Djoser</a>
</li>
<li>
<a href="#django-rest-auth">django-rest-auth</a>
</li>
......@@ -649,74 +641,6 @@ python manage.py createsuperuser
</ul>
<p>Unauthenticated responses that are denied permission will result in an <code>HTTP 403 Forbidden</code> response.</p>
<p>If you're using an AJAX style API with SessionAuthentication, you'll need to make sure you include a valid CSRF token for any "unsafe" HTTP method calls, such as <code>PUT</code>, <code>PATCH</code>, <code>POST</code> or <code>DELETE</code> requests. See the <a href="https://docs.djangoproject.com/en/dev/ref/csrf/#ajax">Django CSRF documentation</a> for more details.</p>
<h2 id="oauthauthentication">OAuthAuthentication</h2>
<p>This authentication uses <a href="http://oauth.net/core/1.0a">OAuth 1.0a</a> authentication scheme. OAuth 1.0a provides signature validation which provides a reasonable level of security over plain non-HTTPS connections. However, it may also be considered more complicated than OAuth2, as it requires clients to sign their requests.</p>
<p>This authentication class depends on the optional <code>django-oauth-plus</code> and <code>oauth2</code> packages. In order to make it work you must install these packages and add <code>oauth_provider</code> to your <code>INSTALLED_APPS</code>:</p>
<pre><code>INSTALLED_APPS = (
...
`oauth_provider`,
)
</code></pre>
<p>Don't forget to run <code>syncdb</code> once you've added the package.</p>
<pre><code>python manage.py syncdb
</code></pre>
<h4 id="getting-started-with-django-oauth-plus">Getting started with django-oauth-plus</h4>
<p>The OAuthAuthentication class only provides token verification and signature validation for requests. It doesn't provide authorization flow for your clients. You still need to implement your own views for accessing and authorizing tokens.</p>
<p>The <code>django-oauth-plus</code> package provides simple foundation for classic 'three-legged' oauth flow. Please refer to <a href="http://code.larlet.fr/django-oauth-plus">the documentation</a> for more details.</p>
<h2 id="oauth2authentication">OAuth2Authentication</h2>
<p>This authentication uses <a href="http://tools.ietf.org/html/rfc6749">OAuth 2.0</a> authentication scheme. OAuth2 is more simple to work with than OAuth1, and provides much better security than simple token authentication. It is an unauthenticated scheme, and requires you to use an HTTPS connection.</p>
<p>This authentication class depends on the optional <a href="https://github.com/caffeinehit/django-oauth2-provider">django-oauth2-provider</a> project. In order to make it work you must install this package and add <code>provider</code> and <code>provider.oauth2</code> to your <code>INSTALLED_APPS</code>:</p>
<pre><code>INSTALLED_APPS = (
...
'provider',
'provider.oauth2',
)
</code></pre>
<p>Then add <code>OAuth2Authentication</code> to your global <code>DEFAULT_AUTHENTICATION_CLASSES</code> setting:</p>
<pre><code>'DEFAULT_AUTHENTICATION_CLASSES': (
'rest_framework.authentication.OAuth2Authentication',
),
</code></pre>
<p>You must also include the following in your root <code>urls.py</code> module:</p>
<pre><code>url(r'^oauth2/', include('provider.oauth2.urls', namespace='oauth2')),
</code></pre>
<p>Note that the <code>namespace='oauth2'</code> argument is required.</p>
<p>Finally, sync your database.</p>
<pre><code>python manage.py syncdb
python manage.py migrate
</code></pre>
<hr />
<p><strong>Note:</strong> If you use <code>OAuth2Authentication</code> in production you must ensure that your API is only available over <code>https</code>.</p>
<hr />
<h4 id="getting-started-with-django-oauth2-provider">Getting started with django-oauth2-provider</h4>
<p>The <code>OAuth2Authentication</code> class only provides token verification for requests. It doesn't provide authorization flow for your clients.</p>
<p>The OAuth 2 authorization flow is taken care by the <a href="https://github.com/caffeinehit/django-oauth2-provider">django-oauth2-provider</a> dependency. A walkthrough is given here, but for more details you should refer to <a href="https://django-oauth2-provider.readthedocs.org/en/latest/">the documentation</a>.</p>
<p>To get started:</p>
<h5 id="1-create-a-client">1. Create a client</h5>
<p>You can create a client, either through the shell, or by using the Django admin.</p>
<p>Go to the admin panel and create a new <code>Provider.Client</code> entry. It will create the <code>client_id</code> and <code>client_secret</code> properties for you.</p>
<h5 id="2-request-an-access-token">2. Request an access token</h5>
<p>To request an access token, submit a <code>POST</code> request to the url <code>/oauth2/access_token</code> with the following fields:</p>
<ul>
<li><code>client_id</code> the client id you've just configured at the previous step.</li>
<li><code>client_secret</code> again configured at the previous step.</li>
<li><code>username</code> the username with which you want to log in.</li>
<li><code>password</code> well, that speaks for itself.</li>
</ul>
<p>You can use the command line to test that your local configuration is working:</p>
<pre><code>curl -X POST -d "client_id=YOUR_CLIENT_ID&amp;client_secret=YOUR_CLIENT_SECRET&amp;grant_type=password&amp;username=YOUR_USERNAME&amp;password=YOUR_PASSWORD" http://localhost:8000/oauth2/access_token/
</code></pre>
<p>You should get a response that looks something like this:</p>
<pre><code>{"access_token": "&lt;your-access-token&gt;", "scope": "read", "expires_in": 86399, "refresh_token": "&lt;your-refresh-token&gt;"}
</code></pre>
<h5 id="3-access-the-api">3. Access the API</h5>
<p>The only thing needed to make the <code>OAuth2Authentication</code> class work is to insert the <code>access_token</code> you've received in the <code>Authorization</code> request header.</p>
<p>The command line to test the authentication looks like:</p>
<pre><code>curl -H "Authorization: Bearer &lt;your-access-token&gt;" http://localhost:8000/api/
</code></pre>
<h3 id="alternative-oauth-2-implementations">Alternative OAuth 2 implementations</h3>
<p>Note that <a href="https://github.com/evonove/django-oauth-toolkit">Django OAuth Toolkit</a> is an alternative external package that also includes OAuth 2.0 support for REST framework.</p>
<hr />
<h1 id="custom-authentication">Custom authentication</h1>
<p>To implement a custom authentication scheme, subclass <code>BaseAuthentication</code> and override the <code>.authenticate(self, request)</code> method. The method should return a two-tuple of <code>(user, auth)</code> if authentication succeeds, or <code>None</code> otherwise.</p>
<p>In some circumstances instead of returning <code>None</code>, you may want to raise an <code>AuthenticationFailed</code> exception from the <code>.authenticate()</code> method.</p>
......@@ -749,10 +673,35 @@ class ExampleAuthentication(authentication.BaseAuthentication):
<hr />
<h1 id="third-party-packages">Third party packages</h1>
<p>The following third party packages are also available.</p>
<h2 id="django-oauth-toolkit">Django OAuth Toolkit</h2>
<p>The <a href="https://github.com/evonove/django-oauth-toolkit">Django OAuth Toolkit</a> package provides OAuth 2.0 support, and works with Python 2.7 and Python 3.3+. The package is maintained by <a href="https://github.com/evonove/">Evonove</a> and uses the excellent <a href="https://github.com/idan/oauthlib">OAuthLib</a>. The package is well documented, and well supported and is currently our <strong>recommended package for OAuth 2.0 support</strong>.</p>
<h4 id="installation-configuration">Installation &amp; configuration</h4>
<p>Install using <code>pip</code>.</p>
<pre><code>pip install django-oauth-toolkit
</code></pre>
<p>Add the package to your <code>INSTALLED_APPS</code> and modify your REST framework settings.</p>
<pre><code>INSTALLED_APPS = (
...
'oauth2_provider',
)
REST_FRAMEWORK = {
'DEFAULT_AUTHENTICATION_CLASSES': (
'oauth2_provider.ext.rest_framework.OAuth2Authentication',
)
}
</code></pre>
<p>For more details see the <a href="https://django-oauth-toolkit.readthedocs.org/en/latest/rest-framework/getting_started.html">Django REST framework - Getting started</a> documentation.</p>
<h2 id="django-rest-framework-oauth">Django REST framework OAuth</h2>
<p>The <a href="http://jpadilla.github.io/django-rest-framework-oauth/">Django REST framework OAuth</a> package provides both OAuth1 and OAuth2 support for REST framework.</p>
<p>This package was previously included directly in REST framework but is now supported and maintained as a third party package.</p>
<h4 id="installation-configuration_1">Installation &amp; configuration</h4>
<p>Install the package using <code>pip</code>.</p>
<pre><code>pip install djangorestframework-oauth
</code></pre>
<p>For details on configuration and usage see the Django REST framework OAuth documentation for <a href="http://jpadilla.github.io/django-rest-framework-oauth/authentication/">authentication</a> and <a href="http://jpadilla.github.io/django-rest-framework-oauth/permissions/">permissions</a>.</p>
<h2 id="digest-authentication">Digest Authentication</h2>
<p>HTTP digest authentication is a widely implemented scheme that was intended to replace HTTP basic authentication, and which provides a simple encrypted authentication mechanism. <a href="https://github.com/juanriaza">Juan Riaza</a> maintains the <a href="https://github.com/juanriaza/django-rest-framework-digestauth">djangorestframework-digestauth</a> package which provides HTTP digest authentication support for REST framework.</p>
<h2 id="django-oauth-toolkit">Django OAuth Toolkit</h2>
<p>The <a href="https://github.com/evonove/django-oauth-toolkit">Django OAuth Toolkit</a> package provides OAuth 2.0 support, and works with Python 2.7 and Python 3.3+. The package is maintained by <a href="https://github.com/evonove/">Evonove</a> and uses the excellent <a href="https://github.com/idan/oauthlib">OAuthLib</a>. The package is well documented, and comes as a recommended alternative for OAuth 2.0 support.</p>
<h2 id="django-oauth2-consumer">Django OAuth2 Consumer</h2>
<p>The <a href="https://github.com/Rediker-Software/doac">Django OAuth2 Consumer</a> library from <a href="https://github.com/Rediker-Software">Rediker Software</a> is another package that provides <a href="https://github.com/Rediker-Software/doac/blob/master/docs/integrations.md#">OAuth 2.0 support for REST framework</a>. The package includes token scoping permissions on tokens, which allows finer-grained access to your API.</p>
<h2 id="json-web-token-authentication">JSON Web Token Authentication</h2>
......@@ -763,6 +712,8 @@ class ExampleAuthentication(authentication.BaseAuthentication):
<p>HTTP Signature (currently a <a href="https://datatracker.ietf.org/doc/draft-cavage-http-signatures/">IETF draft</a>) provides a way to achieve origin authentication and message integrity for HTTP messages. Similar to <a href="http://docs.aws.amazon.com/general/latest/gr/signature-version-4.html">Amazon's HTTP Signature scheme</a>, used by many of its services, it permits stateless, per-request authentication. <a href="https://github.com/etoccalino/">Elvio Toccalino</a> maintains the <a href="https://github.com/etoccalino/django-rest-framework-httpsignature">djangorestframework-httpsignature</a> package which provides an easy to use HTTP Signature Authentication mechanism.</p>
<h2 id="djoser">Djoser</h2>
<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>
</div>
<!--/span-->
......
api-guide/content-negotiation/index.html
......@@ -65,7 +65,7 @@
<a class="repo-link btn btn-inverse btn-small " rel="prev" href="../metadata">
Next <i class="icon-arrow-right icon-white"></i>
</a>
<a class="repo-link btn btn-inverse btn-small " rel="next" href="../pagination">
<a class="repo-link btn btn-inverse btn-small " rel="next" href="../versioning">
<i class="icon-arrow-left icon-white"></i> Previous
</a>
<a class="repo-link btn btn-inverse btn-small" href="#searchModal" data-toggle="modal"><i class="icon-search icon-white"></i> Search</a>
......@@ -188,6 +188,10 @@
<a href="../pagination">Pagination</a>
</li>
<li >
<a href="../versioning">Versioning</a>
</li>
<li class="active" >
<a href=".">Content negotiation</a>
</li>
......@@ -232,6 +236,10 @@
</li>
<li >
<a href="../../topics/internationalization">Internationalization</a>
</li>
<li >
<a href="../../topics/ajax-csrf-cors">AJAX, CSRF & CORS</a>
</li>
......@@ -260,23 +268,11 @@
</li>
<li >
<a href="../../topics/rest-framework-2-announcement">2.0 Announcement</a>
</li>
<li >
<a href="../../topics/2.2-announcement">2.2 Announcement</a>
</li>
<li >
<a href="../../topics/2.3-announcement">2.3 Announcement</a>
</li>
<li >
<a href="../../topics/2.4-announcement">2.4 Announcement</a>
<a href="../../topics/3.0-announcement">3.0 Announcement</a>
</li>
<li >
<a href="../../topics/3.0-announcement">3.0 Announcement</a>
<a href="../../topics/3.1-announcement">3.1 Announcement</a>
</li>
<li >
......@@ -287,10 +283,6 @@
<a href="../../topics/release-notes">Release Notes</a>
</li>
<li >
<a href="../../topics/credits">Credits</a>
</li>
</ul>
</li>
......
api-guide/exceptions/index.html
......@@ -189,6 +189,10 @@
</li>
<li >
<a href="../versioning">Versioning</a>
</li>
<li >
<a href="../content-negotiation">Content negotiation</a>
</li>
......@@ -232,6 +236,10 @@
</li>
<li >
<a href="../../topics/internationalization">Internationalization</a>
</li>
<li >
<a href="../../topics/ajax-csrf-cors">AJAX, CSRF & CORS</a>
</li>
......@@ -260,23 +268,11 @@
</li>
<li >
<a href="../../topics/rest-framework-2-announcement">2.0 Announcement</a>
</li>
<li >
<a href="../../topics/2.2-announcement">2.2 Announcement</a>
</li>
<li >
<a href="../../topics/2.3-announcement">2.3 Announcement</a>
</li>
<li >
<a href="../../topics/2.4-announcement">2.4 Announcement</a>
<a href="../../topics/3.0-announcement">3.0 Announcement</a>
</li>
<li >
<a href="../../topics/3.0-announcement">3.0 Announcement</a>
<a href="../../topics/3.1-announcement">3.1 Announcement</a>
</li>
<li >
......@@ -287,10 +283,6 @@
<a href="../../topics/release-notes">Release Notes</a>
</li>
<li >
<a href="../../topics/credits">Credits</a>
</li>
</ul>
</li>
......@@ -394,10 +386,18 @@
</li>
<li>
<a href="#notfound">NotFound</a>
</li>
<li>
<a href="#methodnotallowed">MethodNotAllowed</a>
</li>
<li>
<a href="#notacceptable">NotAcceptable</a>
</li>
<li>
<a href="#unsupportedmediatype">UnsupportedMediaType</a>
</li>
......@@ -464,7 +464,7 @@ Content-Length: 94
</code></pre>
<h2 id="custom-exception-handling">Custom exception handling</h2>
<p>You can implement custom exception handling by creating a handler function that converts exceptions raised in your API views into response objects. This allows you to control the style of error responses used by your API.</p>
<p>The function must take a single argument, which is the exception to be handled, and should either return a <code>Response</code> object, or return <code>None</code> if the exception cannot be handled. If the handler returns <code>None</code> then the exception will be re-raised and Django will return a standard HTTP 500 'server error' response.</p>
<p>The function must take a pair of arguments, this first is the exception to be handled, and the second is a dictionary containing any extra context such as the view currently being handled. The exception handler function should either return a <code>Response</code> object, or return <code>None</code> if the exception cannot be handled. If the handler returns <code>None</code> then the exception will be re-raised and Django will return a standard HTTP 500 'server error' response.</p>
<p>For example, you might want to ensure that all error responses include the HTTP status code in the body of the response, like so:</p>
<pre><code>HTTP/1.1 405 Method Not Allowed
Content-Type: application/json
......@@ -475,10 +475,10 @@ Content-Length: 62
<p>In order to alter the style of the response, you could write the following custom exception handler:</p>
<pre><code>from rest_framework.views import exception_handler
def custom_exception_handler(exc):
def custom_exception_handler(exc, context):
# Call REST framework's default exception handler first,
# to get the standard error response.
response = exception_handler(exc)
response = exception_handler(exc, context)
# Now add the HTTP status code to the response.
if response is not None:
......@@ -486,6 +486,7 @@ def custom_exception_handler(exc):
return response
</code></pre>
<p>The context argument is not used by the default handler, but can be useful if the exception handler needs further information such as the view currently being handled, which can be accessed as <code>context['view']</code>.</p>
<p>The exception handler must also be configured in your settings, using the <code>EXCEPTION_HANDLER</code> setting key. For example:</p>
<pre><code>REST_FRAMEWORK = {
'EXCEPTION_HANDLER': 'my_project.my_app.utils.custom_exception_handler'
......@@ -526,10 +527,18 @@ class ServiceUnavailable(APIException):
<p><strong>Signature:</strong> <code>PermissionDenied(detail=None)</code></p>
<p>Raised when an authenticated request fails the permission checks.</p>
<p>By default this exception results in a response with the HTTP status code "403 Forbidden".</p>
<h2 id="notfound">NotFound</h2>
<p><strong>Signature:</strong> <code>NotFound(detail=None)</code></p>
<p>Raised when a resource does not exists at the given URL. This exception is equivalent to the standard <code>Http404</code> Django exception.</p>
<p>By default this exception results in a response with the HTTP status code "404 Not Found".</p>
<h2 id="methodnotallowed">MethodNotAllowed</h2>
<p><strong>Signature:</strong> <code>MethodNotAllowed(method, detail=None)</code></p>
<p>Raised when an incoming request occurs that does not map to a handler method on the view.</p>
<p>By default this exception results in a response with the HTTP status code "405 Method Not Allowed".</p>
<h2 id="notacceptable">NotAcceptable</h2>
<p><strong>Signature:</strong> <code>NotAcceptable(detail=None)</code></p>
<p>Raised when an incoming request occurs with an <code>Accept</code> header that cannot be satisfied by any of the available renderers.</p>
<p>By default this exception results in a response with the HTTP status code "406 Not Acceptable".</p>
<h2 id="unsupportedmediatype">UnsupportedMediaType</h2>
<p><strong>Signature:</strong> <code>UnsupportedMediaType(media_type, detail=None)</code></p>
<p>Raised if there are no parsers that can handle the content type of the request data when accessing <code>request.data</code>.</p>
......
api-guide/fields/index.html
......@@ -189,6 +189,10 @@
</li>
<li >
<a href="../versioning">Versioning</a>
</li>
<li >
<a href="../content-negotiation">Content negotiation</a>
</li>
......@@ -232,6 +236,10 @@
</li>
<li >
<a href="../../topics/internationalization">Internationalization</a>
</li>
<li >
<a href="../../topics/ajax-csrf-cors">AJAX, CSRF & CORS</a>
</li>
......@@ -260,23 +268,11 @@
</li>
<li >
<a href="../../topics/rest-framework-2-announcement">2.0 Announcement</a>
</li>
<li >
<a href="../../topics/2.2-announcement">2.2 Announcement</a>
</li>
<li >
<a href="../../topics/2.3-announcement">2.3 Announcement</a>
</li>
<li >
<a href="../../topics/2.4-announcement">2.4 Announcement</a>
<a href="../../topics/3.0-announcement">3.0 Announcement</a>
</li>
<li >
<a href="../../topics/3.0-announcement">3.0 Announcement</a>
<a href="../../topics/3.1-announcement">3.1 Announcement</a>
</li>
<li >
......@@ -287,10 +283,6 @@
<a href="../../topics/release-notes">Release Notes</a>
</li>
<li >
<a href="../../topics/credits">Credits</a>
</li>
</ul>
</li>
......@@ -661,11 +653,12 @@ color_channel = serializers.ChoiceField(
<h2 id="charfield">CharField</h2>
<p>A text representation. Optionally validates the text to be shorter than <code>max_length</code> and longer than <code>min_length</code>.</p>
<p>Corresponds to <code>django.db.models.fields.CharField</code> or <code>django.db.models.fields.TextField</code>.</p>
<p><strong>Signature:</strong> <code>CharField(max_length=None, min_length=None, allow_blank=False)</code></p>
<p><strong>Signature:</strong> <code>CharField(max_length=None, min_length=None, allow_blank=False, trim_whitespace=True)</code></p>
<ul>
<li><code>max_length</code> - Validates that the input contains no more than this number of characters.</li>
<li><code>min_length</code> - Validates that the input contains no fewer than this number of characters.</li>
<li><code>allow_blank</code> - If set to <code>True</code> then the empty string should be considered a valid value. If set to <code>False</code> then the empty string is considered invalid and will raise a validation error. Defaults to <code>False</code>.</li>
<li><code>trim_whitespace</code> - If set to <code>True</code> then leading and trailing whitespace is trimmed. Defaults to <code>True</code>.</li>
</ul>
<p>The <code>allow_null</code> option is also available for string fields, although its usage is discouraged in favor of <code>allow_blank</code>. It is valid to set both <code>allow_blank=True</code> and <code>allow_null=True</code>, but doing so means that there will be two differing types of empty value permissible for string representations, which can lead to data inconsistencies and subtle application bugs.</p>
<h2 id="emailfield">EmailField</h2>
......
api-guide/filtering/index.html
......@@ -189,6 +189,10 @@
</li>
<li >
<a href="../versioning">Versioning</a>
</li>
<li >
<a href="../content-negotiation">Content negotiation</a>
</li>
......@@ -232,6 +236,10 @@
</li>
<li >
<a href="../../topics/internationalization">Internationalization</a>
</li>
<li >
<a href="../../topics/ajax-csrf-cors">AJAX, CSRF & CORS</a>
</li>
......@@ -260,23 +268,11 @@
</li>
<li >
<a href="../../topics/rest-framework-2-announcement">2.0 Announcement</a>
</li>
<li >
<a href="../../topics/2.2-announcement">2.2 Announcement</a>
</li>
<li >
<a href="../../topics/2.3-announcement">2.3 Announcement</a>
</li>
<li >
<a href="../../topics/2.4-announcement">2.4 Announcement</a>
<a href="../../topics/3.0-announcement">3.0 Announcement</a>
</li>
<li >
<a href="../../topics/3.0-announcement">3.0 Announcement</a>
<a href="../../topics/3.1-announcement">3.1 Announcement</a>
</li>
<li >
......@@ -287,10 +283,6 @@
<a href="../../topics/release-notes">Release Notes</a>
</li>
<li >
<a href="../../topics/credits">Credits</a>
</li>
</ul>
</li>
......
api-guide/format-suffixes/index.html
......@@ -189,6 +189,10 @@
</li>
<li >
<a href="../versioning">Versioning</a>
</li>
<li >
<a href="../content-negotiation">Content negotiation</a>
</li>
......@@ -232,6 +236,10 @@
</li>
<li >
<a href="../../topics/internationalization">Internationalization</a>
</li>
<li >
<a href="../../topics/ajax-csrf-cors">AJAX, CSRF & CORS</a>
</li>
......@@ -260,23 +268,11 @@
</li>
<li >
<a href="../../topics/rest-framework-2-announcement">2.0 Announcement</a>
</li>
<li >
<a href="../../topics/2.2-announcement">2.2 Announcement</a>
</li>
<li >
<a href="../../topics/2.3-announcement">2.3 Announcement</a>
</li>
<li >
<a href="../../topics/2.4-announcement">2.4 Announcement</a>
<a href="../../topics/3.0-announcement">3.0 Announcement</a>
</li>
<li >
<a href="../../topics/3.0-announcement">3.0 Announcement</a>
<a href="../../topics/3.1-announcement">3.1 Announcement</a>
</li>
<li >
......@@ -287,10 +283,6 @@
<a href="../../topics/release-notes">Release Notes</a>
</li>
<li >
<a href="../../topics/credits">Credits</a>
</li>
</ul>
</li>
......
api-guide/generic-views/index.html
......@@ -189,6 +189,10 @@
</li>
<li >
<a href="../versioning">Versioning</a>
</li>
<li >
<a href="../content-negotiation">Content negotiation</a>
</li>
......@@ -232,6 +236,10 @@
</li>
<li >
<a href="../../topics/internationalization">Internationalization</a>
</li>
<li >
<a href="../../topics/ajax-csrf-cors">AJAX, CSRF & CORS</a>
</li>
......@@ -260,23 +268,11 @@
</li>
<li >
<a href="../../topics/rest-framework-2-announcement">2.0 Announcement</a>
</li>
<li >
<a href="../../topics/2.2-announcement">2.2 Announcement</a>
</li>
<li >
<a href="../../topics/2.3-announcement">2.3 Announcement</a>
</li>
<li >
<a href="../../topics/2.4-announcement">2.4 Announcement</a>
<a href="../../topics/3.0-announcement">3.0 Announcement</a>
</li>
<li >
<a href="../../topics/3.0-announcement">3.0 Announcement</a>
<a href="../../topics/3.1-announcement">3.1 Announcement</a>
</li>
<li >
......@@ -287,10 +283,6 @@
<a href="../../topics/release-notes">Release Notes</a>
</li>
<li >
<a href="../../topics/credits">Credits</a>
</li>
</ul>
</li>
......@@ -568,11 +560,9 @@ class UserList(generics.ListCreateAPIView):
<p><strong>Pagination</strong>:</p>
<p>The following attributes are used to control pagination when used with list views.</p>
<ul>
<li><code>paginate_by</code> - The size of pages to use with paginated data. If set to <code>None</code> then pagination is turned off. If unset this uses the same value as the <code>PAGINATE_BY</code> setting, which defaults to <code>None</code>.</li>
<li><code>paginate_by_param</code> - The name of a query parameter, which can be used by the client to override the default page size to use for pagination. If unset this uses the same value as the <code>PAGINATE_BY_PARAM</code> setting, which defaults to <code>None</code>.</li>
<li><code>pagination_serializer_class</code> - The pagination serializer class to use when determining the style of paginated responses. Defaults to the same value as the <code>DEFAULT_PAGINATION_SERIALIZER_CLASS</code> setting.</li>
<li><code>page_kwarg</code> - The name of a URL kwarg or URL query parameter which can be used by the client to control which page is requested. Defaults to <code>'page'</code>.</li>
<li><code>pagination_class</code> - The pagination class that should be used when paginating list results. Defaults to the same value as the <code>DEFAULT_PAGINATION_CLASS</code> setting, which is <code>'rest_framework.pagination.PageNumberPagination'</code>.</li>
</ul>
<p>Note that usage of the <code>paginate_by</code>, <code>paginate_by_param</code> and <code>page_kwarg</code> attributes are now pending deprecation. The <code>pagination_serializer_class</code> attribute and <code>DEFAULT_PAGINATION_SERIALIZER_CLASS</code> setting have been removed completely. Pagination settings should instead be controlled by overriding a pagination class and setting any configuration attributes there. See the pagination documentation for more details.</p>
<p><strong>Filtering</strong>:</p>
<ul>
<li><code>filter_backends</code> - A list of filter backend classes that should be used for filtering the queryset. Defaults to the same value as the <code>DEFAULT_FILTER_BACKENDS</code> setting.</li>
......
api-guide/metadata/index.html
......@@ -189,6 +189,10 @@
</li>
<li >
<a href="../versioning">Versioning</a>
</li>
<li >
<a href="../content-negotiation">Content negotiation</a>
</li>
......@@ -232,6 +236,10 @@
</li>
<li >
<a href="../../topics/internationalization">Internationalization</a>
</li>
<li >
<a href="../../topics/ajax-csrf-cors">AJAX, CSRF & CORS</a>
</li>
......@@ -260,23 +268,11 @@
</li>
<li >
<a href="../../topics/rest-framework-2-announcement">2.0 Announcement</a>
</li>
<li >
<a href="../../topics/2.2-announcement">2.2 Announcement</a>
</li>
<li >
<a href="../../topics/2.3-announcement">2.3 Announcement</a>
</li>
<li >
<a href="../../topics/2.4-announcement">2.4 Announcement</a>
<a href="../../topics/3.0-announcement">3.0 Announcement</a>
</li>
<li >
<a href="../../topics/3.0-announcement">3.0 Announcement</a>
<a href="../../topics/3.1-announcement">3.1 Announcement</a>
</li>
<li >
......@@ -287,10 +283,6 @@
<a href="../../topics/release-notes">Release Notes</a>
</li>
<li >
<a href="../../topics/credits">Credits</a>
</li>
</ul>
</li>
......
api-guide/pagination/index.html
......@@ -62,7 +62,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="../content-negotiation">
<a class="repo-link btn btn-inverse btn-small " rel="prev" href="../versioning">
Next <i class="icon-arrow-right icon-white"></i>
</a>
<a class="repo-link btn btn-inverse btn-small " rel="next" href="../filtering">
......@@ -189,6 +189,10 @@
</li>
<li >
<a href="../versioning">Versioning</a>
</li>
<li >
<a href="../content-negotiation">Content negotiation</a>
</li>
......@@ -232,6 +236,10 @@
</li>
<li >
<a href="../../topics/internationalization">Internationalization</a>
</li>
<li >
<a href="../../topics/ajax-csrf-cors">AJAX, CSRF & CORS</a>
</li>
......@@ -260,23 +268,11 @@
</li>
<li >
<a href="../../topics/rest-framework-2-announcement">2.0 Announcement</a>
</li>
<li >
<a href="../../topics/2.2-announcement">2.2 Announcement</a>
</li>
<li >
<a href="../../topics/2.3-announcement">2.3 Announcement</a>
</li>
<li >
<a href="../../topics/2.4-announcement">2.4 Announcement</a>
<a href="../../topics/3.0-announcement">3.0 Announcement</a>
</li>
<li >
<a href="../../topics/3.0-announcement">3.0 Announcement</a>
<a href="../../topics/3.1-announcement">3.1 Announcement</a>
</li>
<li >
......@@ -287,10 +283,6 @@
<a href="../../topics/release-notes">Release Notes</a>
</li>
<li >
<a href="../../topics/credits">Credits</a>
</li>
</ul>
</li>
......@@ -358,22 +350,38 @@
<li>
<a href="#paginating-basic-data">Paginating basic data</a>
<a href="#setting-the-pagination-style">Setting the pagination style</a>
</li>
<li>
<a href="#modifying-the-pagination-style">Modifying the pagination style</a>
</li>
<li class="main">
<a href="#api-reference">API Reference</a>
</li>
<li>
<a href="#pagenumberpagination">PageNumberPagination</a>
</li>
<li>
<a href="#paginating-querysets">Paginating QuerySets</a>
<a href="#limitoffsetpagination">LimitOffsetPagination</a>
</li>
<li>
<a href="#pagination-in-the-generic-views">Pagination in the generic views</a>
<a href="#cursorpagination">CursorPagination</a>
</li>
<li class="main">
<a href="#custom-pagination-serializers">Custom pagination serializers</a>
<a href="#custom-pagination-styles">Custom pagination styles</a>
</li>
......@@ -382,7 +390,23 @@
</li>
<li>
<a href="#using-your-custom-pagination-serializer">Using your custom pagination serializer</a>
<a href="#header-based-pagination">Header based pagination</a>
</li>
<li>
<a href="#using-your-custom-pagination-class">Using your custom pagination class</a>
</li>
<li class="main">
<a href="#html-pagination-controls">HTML pagination controls</a>
</li>
<li>
<a href="#customizing-the-controls">Customizing the controls</a>
</li>
......@@ -421,123 +445,230 @@
<p>Django provides a few classes that help you manage paginated data – that is, data that’s split across several pages, with “Previous/Next” links.</p>
<p>&mdash; <a href="https://docs.djangoproject.com/en/dev/topics/pagination/">Django documentation</a></p>
</blockquote>
<p>REST framework includes a <code>PaginationSerializer</code> class that makes it easy to return paginated data in a way that can then be rendered to arbitrary media types.</p>
<h2 id="paginating-basic-data">Paginating basic data</h2>
<p>Let's start by taking a look at an example from the Django documentation.</p>
<pre><code>from django.core.paginator import Paginator
objects = ['john', 'paul', 'george', 'ringo']
paginator = Paginator(objects, 2)
page = paginator.page(1)
page.object_list
# ['john', 'paul']
<p>REST framework includes support for customizable pagination styles. This allows you to modify how large result sets are split into individual pages of data.</p>
<p>The pagination API can support either:</p>
<ul>
<li>Pagination links that are provided as part of the content of the response.</li>
<li>Pagination links that are included in response headers, such as <code>Content-Range</code> or <code>Link</code>.</li>
</ul>
<p>The built-in styles currently all use links included as part of the content of the response. This style is more accessible when using the browsable API.</p>
<p>Pagination is only performed automatically if you're using the generic views or viewsets. If you're using a regular <code>APIView</code>, you'll need to call into the pagination API yourself to ensure you return a paginated response. See the source code for the <code>mixins.ListMixin</code> and <code>generics.GenericAPIView</code> classes for an example.</p>
<h2 id="setting-the-pagination-style">Setting the pagination style</h2>
<p>The default pagination style may be set globally, using the <code>DEFAULT_PAGINATION_CLASS</code> settings key. For example, to use the built-in limit/offset pagination, you would do:</p>
<pre><code>REST_FRAMEWORK = {
'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.LimitOffsetPagination'
}
</code></pre>
<p>At this point we've got a page object. If we wanted to return this page object as a JSON response, we'd need to provide the client with context such as next and previous links, so that it would be able to page through the remaining results.</p>
<pre><code>from rest_framework.pagination import PaginationSerializer
serializer = PaginationSerializer(instance=page)
serializer.data
# {'count': 4, 'next': '?page=2', 'previous': None, 'results': [u'john', u'paul']}
<p>You can also set the pagination class on an individual view by using the <code>pagination_class</code> attribute. Typically you'll want to use the same pagination style throughout your API, although you might want to vary individual aspects of the pagination, such as default or maximum page size, on a per-view basis.</p>
<h2 id="modifying-the-pagination-style">Modifying the pagination style</h2>
<p>If you want to modify particular aspects of the pagination style, you'll want to override one of the pagination classes, and set the attributes that you want to change.</p>
<pre><code>class LargeResultsSetPagination(PageNumberPagination):
page_size = 1000
page_size_query_param = 'page_size'
max_page_size = 10000
class StandardResultsSetPagination(PageNumberPagination):
page_size = 100
page_size_query_param = 'page_size'
max_page_size = 1000
</code></pre>
<p>You can then apply your new style to a view using the <code>.pagination_class</code> attribute:</p>
<pre><code>class BillingRecordsView(generics.ListAPIView):
queryset = Billing.objects.all()
serializer = BillingRecordsSerializer
pagination_class = LargeResultsSetPagination
</code></pre>
<p>Or apply the style globally, using the <code>DEFAULT_PAGINATION_CLASS</code> settings key. For example:</p>
<pre><code>REST_FRAMEWORK = {
'DEFAULT_PAGINATION_CLASS': 'apps.core.pagination.StandardResultsSetPagination'
}
</code></pre>
<hr />
<h1 id="api-reference">API Reference</h1>
<h2 id="pagenumberpagination">PageNumberPagination</h2>
<p>This pagination style accepts a single number page number in the request query parameters.</p>
<p><strong>Request</strong>:</p>
<pre><code>GET https://api.example.org/accounts/?page=4
</code></pre>
<p>The <code>context</code> argument of the <code>PaginationSerializer</code> class may optionally include the request. If the request is included in the context then the next and previous links returned by the serializer will use absolute URLs instead of relative URLs.</p>
<pre><code>request = RequestFactory().get('/foobar')
serializer = PaginationSerializer(instance=page, context={'request': request})
serializer.data
# {'count': 4, 'next': 'http://testserver/foobar?page=2', 'previous': None, 'results': [u'john', u'paul']}
<p><strong>Response</strong>:</p>
<pre><code>HTTP 200 OK
{
"count": 1023
"next": "https://api.example.org/accounts/?page=5",
"previous": "https://api.example.org/accounts/?page=3",
"results": [
…
]
}
</code></pre>
<p>We could now return that data in a <code>Response</code> object, and it would be rendered into the correct media type.</p>
<h2 id="paginating-querysets">Paginating QuerySets</h2>
<p>Our first example worked because we were using primitive objects. If we wanted to paginate a queryset or other complex data, we'd need to specify a serializer to use to serialize the result set itself.</p>
<p>We can do this using the <code>object_serializer_class</code> attribute on the inner <code>Meta</code> class of the pagination serializer. For example.</p>
<pre><code>class UserSerializer(serializers.ModelSerializer):
"""
Serializes user querysets.
"""
class Meta:
model = User
fields = ('username', 'email')
class PaginatedUserSerializer(pagination.PaginationSerializer):
"""
Serializes page objects of user querysets.
"""
class Meta:
object_serializer_class = UserSerializer
<h4 id="setup">Setup</h4>
<p>To enable the <code>PageNumberPagination</code> style globally, use the following configuration, modifying the <code>DEFAULT_PAGE_SIZE</code> as desired:</p>
<pre><code>REST_FRAMEWORK = {
'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.PageNumberPagination',
'DEFAULT_PAGE_SIZE': 100
}
</code></pre>
<p>We could now use our pagination serializer in a view like this.</p>
<pre><code>@api_view('GET')
def user_list(request):
queryset = User.objects.all()
paginator = Paginator(queryset, 20)
page = request.QUERY_PARAMS.get('page')
try:
users = paginator.page(page)
except PageNotAnInteger:
# If page is not an integer, deliver first page.
users = paginator.page(1)
except EmptyPage:
# If page is out of range (e.g. 9999),
# deliver last page of results.
users = paginator.page(paginator.num_pages)
serializer_context = {'request': request}
serializer = PaginatedUserSerializer(users,
context=serializer_context)
return Response(serializer.data)
<p>On <code>GenericAPIView</code> subclasses you may also set the <code>pagination_class</code> attribute to select <code>PageNumberPagination</code> on a per-view basis.</p>
<h4 id="configuration">Configuration</h4>
<p>The <code>PageNumberPagination</code> class includes a number of attributes that may be overridden to modify the pagination style.</p>
<p>To set these attributes you should override the <code>PageNumberPagination</code> class, and then enable your custom pagination class as above.</p>
<ul>
<li><code>page_size</code> - A numeric value indicating the page size. If set, this overrides the <code>DEFAULT_PAGE_SIZE</code> setting. Defaults to the same value as the <code>DEFAULT_PAGE_SIZE</code> settings key.</li>
<li><code>page_query_param</code> - A string value indicating the name of the query parameter to use for the pagination control.</li>
<li><code>page_size_query_param</code> - If set, this is a string value indicating the name of a query parameter that allows the client to set the page size on a per-request basis. Defaults to <code>None</code>, indicating that the client may not control the requested page size.</li>
<li><code>max_page_size</code> - If set, this is a numeric value indicating the maximum allowable requested page size. This attribute is only valid if <code>page_size_query_param</code> is also set.</li>
<li><code>last_page_strings</code> - A list or tuple of string values indicating values that may be used with the <code>page_query_param</code> to request the final page in the set. Defaults to <code>('last',)</code></li>
<li><code>template</code> - The name of a template to use when rendering pagination controls in the browsable API. May be overridden to modify the rendering style, or set to <code>None</code> to disable HTML pagination controls completely. Defaults to <code>"rest_framework/pagination/numbers.html"</code>.</li>
</ul>
<hr />
<h2 id="limitoffsetpagination">LimitOffsetPagination</h2>
<p>This pagination style mirrors the syntax used when looking up multiple database records. The client includes both a "limit" and an
"offset" query parameter. The limit indicates the maximum number of items to return, and is equivalent to the <code>page_size</code> in other styles. The offset indicates the starting position of the query in relation to the complete set of unpaginated items.</p>
<p><strong>Request</strong>:</p>
<pre><code>GET https://api.example.org/accounts/?limit=100&amp;offset=400
</code></pre>
<h2 id="pagination-in-the-generic-views">Pagination in the generic views</h2>
<p>The generic class based views <code>ListAPIView</code> and <code>ListCreateAPIView</code> provide pagination of the returned querysets by default. You can customise this behaviour by altering the pagination style, by modifying the default number of results, by allowing clients to override the page size using a query parameter, or by turning pagination off completely.</p>
<p>The default pagination style may be set globally, using the <code>DEFAULT_PAGINATION_SERIALIZER_CLASS</code>, <code>PAGINATE_BY</code>, <code>PAGINATE_BY_PARAM</code>, and <code>MAX_PAGINATE_BY</code> settings. For example.</p>
<p><strong>Response</strong>:</p>
<pre><code>HTTP 200 OK
{
"count": 1023
"next": "https://api.example.org/accounts/?limit=100&amp;offset=500",
"previous": "https://api.example.org/accounts/?limit=100&amp;offset=300",
"results": [
…
]
}
</code></pre>
<h4 id="setup_1">Setup</h4>
<p>To enable the <code>PageNumberPagination</code> style globally, use the following configuration:</p>
<pre><code>REST_FRAMEWORK = {
'PAGINATE_BY': 10, # Default to 10
'PAGINATE_BY_PARAM': 'page_size', # Allow client to override, using `?page_size=xxx`.
'MAX_PAGINATE_BY': 100 # Maximum limit allowed when using `?page_size=xxx`.
'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.LimitOffsetPagination'
}
</code></pre>
<p>You can also set the pagination style on a per-view basis, using the <code>ListAPIView</code> generic class-based view.</p>
<pre><code>class PaginatedListView(ListAPIView):
queryset = ExampleModel.objects.all()
serializer_class = ExampleModelSerializer
paginate_by = 10
paginate_by_param = 'page_size'
max_paginate_by = 100
<p>Optionally, you may also set a <code>DEFAULT_PAGE_SIZE</code> key. If the <code>DEFAULT_PAGE_SIZE</code> parameter is also used then the <code>limit</code> query parameter will be optional, and may be omitted by the client.</p>
<p>On <code>GenericAPIView</code> subclasses you may also set the <code>pagination_class</code> attribute to select <code>LimitOffsetPagination</code> on a per-view basis.</p>
<h4 id="configuration_1">Configuration</h4>
<p>The <code>LimitOffsetPagination</code> class includes a number of attributes that may be overridden to modify the pagination style.</p>
<p>To set these attributes you should override the <code>LimitOffsetPagination</code> class, and then enable your custom pagination class as above.</p>
<ul>
<li><code>default_limit</code> - A numeric value indicating the limit to use if one is not provided by the client in a query parameter. Defaults to the same value as the <code>DEFAULT_PAGE_SIZE</code> settings key.</li>
<li><code>limit_query_param</code> - A string value indicating the name of the "limit" query parameter. Defaults to <code>'limit'</code>.</li>
<li><code>offset_query_param</code> - A string value indicating the name of the "offset" query parameter. Defaults to <code>'offset'</code>.</li>
<li><code>max_limit</code> - If set this is a numeric value indicating the maximum allowable limit that may be requested by the client. Defaults to <code>None</code>.</li>
<li><code>template</code> - The name of a template to use when rendering pagination controls in the browsable API. May be overridden to modify the rendering style, or set to <code>None</code> to disable HTML pagination controls completely. Defaults to <code>"rest_framework/pagination/numbers.html"</code>.</li>
</ul>
<hr />
<h2 id="cursorpagination">CursorPagination</h2>
<p>The cursor-based pagination presents an opaque "cursor" indicator that the client may use to page through the result set. This pagination style only presents forward and reverse controls, and does not allow the client to navigate to arbitrary positions.</p>
<p>Cursor based pagination requires that there is a unique, unchanging ordering of items in the result set. This ordering might typically be a creation timestamp on the records, as this presents a consistent ordering to paginate against.</p>
<p>Cursor based pagination is more complex than other schemes. It also requires that the result set presents a fixed ordering, and does not allow the client to arbitrarily index into the result set. However it does provide the following benefits:</p>
<ul>
<li>Provides a consistent pagination view. When used properly <code>CursorPagination</code> ensures that the client will never see the same item twice when paging through records, even when new items are being inserted by other clients during the pagination process.</li>
<li>Supports usage with very large datasets. With extremely large datasets pagination using offset-based pagination styles may become inefficient or unusable. Cursor based pagination schemes instead have fixed-time properties, and do not slow down as the dataset size increases.</li>
</ul>
<h4 id="details-and-limitations">Details and limitations</h4>
<p>Proper use of cursor based pagination a little attention to detail. You'll need to think about what ordering you want the scheme to be applied against. The default is to order by <code>"-created"</code>. This assumes that <strong>there must be a 'created' timestamp field</strong> on the model instances, and will present a "timeline" style paginated view, with the most recently added items first.</p>
<p>You can modify the ordering by overriding the <code>'ordering'</code> attribute on the pagination class, or by using the <code>OrderingFilter</code> filter class together with <code>CursorPagination</code>. When used with <code>OrderingFilter</code> you should strongly consider restricting the fields that the user may order by.</p>
<p>Proper usage of cursor pagination should have an ordering field that satisfies the following:</p>
<ul>
<li>Should be an unchanging value, such as a timestamp, slug, or other field that is only set once, on creation.</li>
<li>Should be unique, or nearly unique. Millisecond precision timestamps are a good example. This implementation of cursor pagination uses a smart "position plus offset" style that allows it to properly support not-strictly-unique values as the ordering.</li>
<li>Should be a non-nullable value that can be coerced to a string.</li>
<li>The field should have a database index.</li>
</ul>
<p>Using an ordering field that does not satisfy these constraints will generally still work, but you'll be loosing some of the benefits of cursor pagination.</p>
<p>For more technical details on the implementation we use for cursor pagination, the <a href="http://cramer.io/2011/03/08/building-cursors-for-the-disqus-api/">"Building cursors for the Disqus API"</a> blog post gives a good overview of the basic approach.</p>
<h4 id="setup_2">Setup</h4>
<p>To enable the <code>CursorPagination</code> style globally, use the following configuration, modifying the <code>DEFAULT_PAGE_SIZE</code> as desired:</p>
<pre><code>REST_FRAMEWORK = {
'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.CursorPagination',
'DEFAULT_PAGE_SIZE': 100
}
</code></pre>
<p>Note that using a <code>paginate_by</code> value of <code>None</code> will turn off pagination for the view.
Note if you use the <code>PAGINATE_BY_PARAM</code> settings, you also have to set the <code>paginate_by_param</code> attribute in your view to <code>None</code> in order to turn off pagination for those requests that contain the <code>paginate_by_param</code> parameter.</p>
<p>For more complex requirements such as serialization that differs depending on the requested media type you can override the <code>.get_paginate_by()</code> and <code>.get_pagination_serializer_class()</code> methods.</p>
<p>On <code>GenericAPIView</code> subclasses you may also set the <code>pagination_class</code> attribute to select <code>CursorPagination</code> on a per-view basis.</p>
<h4 id="configuration_2">Configuration</h4>
<p>The <code>CursorPagination</code> class includes a number of attributes that may be overridden to modify the pagination style.</p>
<p>To set these attributes you should override the <code>CursorPagination</code> class, and then enable your custom pagination class as above.</p>
<ul>
<li><code>page_size</code> = A numeric value indicating the page size. If set, this overrides the <code>DEFAULT_PAGE_SIZE</code> setting. Defaults to the same value as the <code>DEFAULT_PAGE_SIZE</code> settings key.</li>
<li><code>cursor_query_param</code> = A string value indicating the name of the "cursor" query parameter. Defaults to <code>'cursor'</code>.</li>
<li><code>ordering</code> = This should be a string, or list of strings, indicating the field against which the cursor based pagination will be applied. For example: <code>ordering = 'slug'</code>. Defaults to <code>-created</code>. This value may also be overridden by using <code>OrderingFilter</code> on the view.</li>
<li><code>template</code> = The name of a template to use when rendering pagination controls in the browsable API. May be overridden to modify the rendering style, or set to <code>None</code> to disable HTML pagination controls completely. Defaults to <code>"rest_framework/pagination/previous_and_next.html"</code>.</li>
</ul>
<hr />
<h1 id="custom-pagination-serializers">Custom pagination serializers</h1>
<p>To create a custom pagination serializer class you should override <code>pagination.BasePaginationSerializer</code> and set the fields that you want the serializer to return.</p>
<p>You can also override the name used for the object list field, by setting the <code>results_field</code> attribute, which defaults to <code>'results'</code>.</p>
<h1 id="custom-pagination-styles">Custom pagination styles</h1>
<p>To create a custom pagination serializer class you should subclass <code>pagination.BasePagination</code> and override the <code>paginate_queryset(self, queryset, request, view=None)</code> and <code>get_paginated_response(self, data)</code> methods:</p>
<ul>
<li>The <code>paginate_queryset</code> method is passed the initial queryset and should return an iterable object that contains only the data in the requested page.</li>
<li>The <code>get_paginated_response</code> method is passed the serialized page data and should return a <code>Response</code> instance.</li>
</ul>
<p>Note that the <code>paginate_queryset</code> method may set state on the pagination instance, that may later be used by the <code>get_paginated_response</code> method.</p>
<h2 id="example">Example</h2>
<p>For example, to nest a pair of links labelled 'prev' and 'next', and set the name for the results field to 'objects', you might use something like this.</p>
<pre><code>from rest_framework import pagination
from rest_framework import serializers
class LinksSerializer(serializers.Serializer):
next = pagination.NextPageField(source='*')
prev = pagination.PreviousPageField(source='*')
class CustomPaginationSerializer(pagination.BasePaginationSerializer):
links = LinksSerializer(source='*') # Takes the page object as the source
total_results = serializers.ReadOnlyField(source='paginator.count')
results_field = 'objects'
<p>Suppose we want to replace the default pagination output style with a modified format that includes the next and previous links under in a nested 'links' key. We could specify a custom pagination class like so:</p>
<pre><code>class CustomPagination(pagination.PageNumberPagination):
def get_paginated_response(self, data):
return Response({
'links': {
'next': self.get_next_link(),
'previous': self.get_previous_link()
},
'count': self.page.paginator.count,
'results': data
})
</code></pre>
<h2 id="using-your-custom-pagination-serializer">Using your custom pagination serializer</h2>
<p>To have your custom pagination serializer be used by default, use the <code>DEFAULT_PAGINATION_SERIALIZER_CLASS</code> setting:</p>
<p>We'd then need to setup the custom class in our configuration:</p>
<pre><code>REST_FRAMEWORK = {
'DEFAULT_PAGINATION_SERIALIZER_CLASS':
'example_app.pagination.CustomPaginationSerializer',
'DEFAULT_PAGINATION_CLASS': 'my_project.apps.core.pagination.CustomPagination',
'PAGE_SIZE': 100
}
</code></pre>
<p>Alternatively, to set your custom pagination serializer on a per-view basis, use the <code>pagination_serializer_class</code> attribute on a generic class based view:</p>
<pre><code>class PaginatedListView(generics.ListAPIView):
model = ExampleModel
pagination_serializer_class = CustomPaginationSerializer
paginate_by = 10
<p>Note that if you care about how the ordering of keys is displayed in responses in the browsable API you might choose to use an <code>OrderedDict</code> when constructing the body of paginated responses, but this is optional.</p>
<h2 id="header-based-pagination">Header based pagination</h2>
<p>Let's modify the built-in <code>PageNumberPagination</code> style, so that instead of include the pagination links in the body of the response, we'll instead include a <code>Link</code> header, in a <a href="https://developer.github.com/guides/traversing-with-pagination/">similar style to the GitHub API</a>.</p>
<pre><code>class LinkHeaderPagination(pagination.PageNumberPagination):
def get_paginated_response(self, data):
next_url = self.get_next_link()
previous_url = self.get_previous_link()
if next_url is not None and previous_url is not None:
link = '&lt;{next_url}; rel="next"&gt;, &lt;{previous_url}; rel="prev"&gt;'
elif next_url is not None:
link = '&lt;{next_url}; rel="next"&gt;'
elif previous_url is not None:
link = '&lt;{previous_url}; rel="prev"&gt;'
else:
link = ''
link = link.format(next_url=next_url, previous_url=previous_url)
headers = {'Link': link} if link else {}
return Response(data, headers=headers)
</code></pre>
<h2 id="using-your-custom-pagination-class">Using your custom pagination class</h2>
<p>To have your custom pagination class be used by default, use the <code>DEFAULT_PAGINATION_CLASS</code> setting:</p>
<pre><code>REST_FRAMEWORK = {
'DEFAULT_PAGINATION_CLASS': 'my_project.apps.core.pagination.LinkHeaderPagination',
'PAGE_SIZE': 100
}
</code></pre>
<p>API responses for list endpoints will now include a <code>Link</code> header, instead of including the pagination links as part of the body of the response, for example:</p>
<hr />
<p><img alt="Link Header" src="../../../img/link-header-pagination.png" /></p>
<p><em>A custom pagination style, using the 'Link' header'</em></p>
<hr />
<h1 id="html-pagination-controls">HTML pagination controls</h1>
<p>By default using the pagination classes will cause HTML pagination controls to be displayed in the browsable API. There are two built-in display styles. The <code>PageNumberPagination</code> and <code>LimitOffsetPagination</code> classes display a list of page numbers with previous and next controls. The <code>CursorPagination</code> class displays a simpler style that only displays a previous and next control.</p>
<h2 id="customizing-the-controls">Customizing the controls</h2>
<p>You can override the templates that render the HTML pagination controls. The two built-in styles are:</p>
<ul>
<li><code>rest_framework/pagination/numbers.html</code></li>
<li><code>rest_framework/pagination/previous_and_next.html</code></li>
</ul>
<p>Providing a template with either of these paths in a global template directory will override the default rendering for the relevant pagination classes.</p>
<p>Alternatively you can disable HTML pagination controls completely by subclassing on of the existing classes, setting <code>template = None</code> as an attribute on the class. You'll then need to configure your <code>DEFAULT_PAGINATION_CLASS</code> settings key to use your custom class as the default pagination style.</p>
<h4 id="low-level-api">Low-level API</h4>
<p>The low-level API for determining if a pagination class should display the controls or not is exposed as a <code>display_page_controls</code> attribute on the pagination instance. Custom pagination classes should be set to <code>True</code> in the <code>paginate_queryset</code> method if they require the HTML pagination controls to be displayed.</p>
<p>The <code>.to_html()</code> and <code>.get_html_context()</code> methods may also be overridden in a custom pagination class in order to further customize how the controls are rendered.</p>
<hr />
<h1 id="third-party-packages">Third party packages</h1>
<p>The following third party packages are also available.</p>
<h2 id="drf-extensions">DRF-extensions</h2>
......
api-guide/parsers/index.html
......@@ -189,6 +189,10 @@
</li>
<li >
<a href="../versioning">Versioning</a>
</li>
<li >
<a href="../content-negotiation">Content negotiation</a>
</li>
......@@ -232,6 +236,10 @@
</li>
<li >
<a href="../../topics/internationalization">Internationalization</a>
</li>
<li >
<a href="../../topics/ajax-csrf-cors">AJAX, CSRF & CORS</a>
</li>
......@@ -260,23 +268,11 @@
</li>
<li >
<a href="../../topics/rest-framework-2-announcement">2.0 Announcement</a>
</li>
<li >
<a href="../../topics/2.2-announcement">2.2 Announcement</a>
</li>
<li >
<a href="../../topics/2.3-announcement">2.3 Announcement</a>
</li>
<li >
<a href="../../topics/2.4-announcement">2.4 Announcement</a>
<a href="../../topics/3.0-announcement">3.0 Announcement</a>
</li>
<li >
<a href="../../topics/3.0-announcement">3.0 Announcement</a>
<a href="../../topics/3.1-announcement">3.1 Announcement</a>
</li>
<li >
......@@ -287,10 +283,6 @@
<a href="../../topics/release-notes">Release Notes</a>
</li>
<li >
<a href="../../topics/credits">Credits</a>
</li>
</ul>
</li>
......@@ -378,14 +370,6 @@
</li>
<li>
<a href="#yamlparser">YAMLParser</a>
</li>
<li>
<a href="#xmlparser">XMLParser</a>
</li>
<li>
<a href="#formparser">FormParser</a>
</li>
......@@ -430,6 +414,14 @@
<li>
<a href="#yaml">YAML</a>
</li>
<li>
<a href="#xml">XML</a>
</li>
<li>
<a href="#messagepack">MessagePack</a>
</li>
......@@ -472,34 +464,34 @@ sending more complex data than simple forms</p>
<p>As an example, if you are sending <code>json</code> encoded data using jQuery with the <a href="http://api.jquery.com/jQuery.ajax/">.ajax() method</a>, you should make sure to include the <code>contentType: 'application/json'</code> setting.</p>
<hr />
<h2 id="setting-the-parsers">Setting the parsers</h2>
<p>The default set of parsers may be set globally, using the <code>DEFAULT_PARSER_CLASSES</code> setting. For example, the following settings would allow requests with <code>YAML</code> content.</p>
<p>The default set of parsers may be set globally, using the <code>DEFAULT_PARSER_CLASSES</code> setting. For example, the following settings would allow only requests with <code>JSON</code> content, instead of the default of JSON or form data.</p>
<pre><code>REST_FRAMEWORK = {
'DEFAULT_PARSER_CLASSES': (
'rest_framework.parsers.YAMLParser',
'rest_framework.parsers.JSONParser',
)
}
</code></pre>
<p>You can also set the parsers used for an individual view, or viewset,
using the <code>APIView</code> class based views.</p>
<pre><code>from rest_framework.parsers import YAMLParser
<pre><code>from rest_framework.parsers import JSONParser
from rest_framework.response import Response
from rest_framework.views import APIView
class ExampleView(APIView):
"""
A view that can accept POST requests with YAML content.
A view that can accept POST requests with JSON content.
"""
parser_classes = (YAMLParser,)
parser_classes = (JSONParser,)
def post(self, request, format=None):
return Response({'received data': request.data})
</code></pre>
<p>Or, if you're using the <code>@api_view</code> decorator with function based views.</p>
<pre><code>@api_view(['POST'])
@parser_classes((YAMLParser,))
@parser_classes((JSONParser,))
def example_view(request, format=None):
"""
A view that can accept POST requests with YAML content.
A view that can accept POST requests with JSON content.
"""
return Response({'received data': request.data})
</code></pre>
......@@ -508,16 +500,6 @@ def example_view(request, format=None):
<h2 id="jsonparser">JSONParser</h2>
<p>Parses <code>JSON</code> request content.</p>
<p><strong>.media_type</strong>: <code>application/json</code></p>
<h2 id="yamlparser">YAMLParser</h2>
<p>Parses <code>YAML</code> request content.</p>
<p>Requires the <code>pyyaml</code> package to be installed.</p>
<p><strong>.media_type</strong>: <code>application/yaml</code></p>
<h2 id="xmlparser">XMLParser</h2>
<p>Parses REST framework's default style of <code>XML</code> request content.</p>
<p>Note that the <code>XML</code> markup language is typically used as the base language for more strictly defined domain-specific languages, such as <code>RSS</code>, <code>Atom</code>, and <code>XHTML</code>.</p>
<p>If you are considering using <code>XML</code> for your API, you may want to consider implementing a custom renderer and parser for your specific requirements, and using an existing domain-specific media-type, or creating your own custom XML-based media-type.</p>
<p>Requires the <code>defusedxml</code> package to be installed.</p>
<p><strong>.media_type</strong>: <code>application/xml</code></p>
<h2 id="formparser">FormParser</h2>
<p>Parses HTML form content. <code>request.data</code> will be populated with a <code>QueryDict</code> of data.</p>
<p>You will typically want to use both <code>FormParser</code> and <code>MultiPartParser</code> together in order to fully support HTML form data.</p>
......@@ -561,7 +543,7 @@ def example_view(request, format=None):
<p>Optional. If supplied, this argument will be a dictionary containing any additional context that may be required to parse the request content.</p>
<p>By default this will include the following keys: <code>view</code>, <code>request</code>, <code>args</code>, <code>kwargs</code>.</p>
<h2 id="example">Example</h2>
<p>The following is an example plaintext parser that will populate the <code>request.data</code> property with a string representing the body of the request. </p>
<p>The following is an example plaintext parser that will populate the <code>request.data</code> property with a string representing the body of the request.</p>
<pre><code>class PlainTextParser(BaseParser):
"""
Plain text parser.
......@@ -578,6 +560,38 @@ def parse(self, stream, media_type=None, parser_context=None):
<hr />
<h1 id="third-party-packages">Third party packages</h1>
<p>The following third party packages are also available.</p>
<h2 id="yaml">YAML</h2>
<p><a href="http://jpadilla.github.io/django-rest-framework-yaml/">REST framework YAML</a> provides <a href="http://www.yaml.org/">YAML</a> parsing and rendering support. It was previously included directly in the REST framework package, and is now instead supported as a third-party package.</p>
<h4 id="installation-configuration">Installation &amp; configuration</h4>
<p>Install using pip.</p>
<pre><code>$ pip install djangorestframework-yaml
</code></pre>
<p>Modify your REST framework settings.</p>
<pre><code>REST_FRAMEWORK = {
'DEFAULT_PARSER_CLASSES': (
'rest_framework_yaml.parsers.YAMLParser',
),
'DEFAULT_RENDERER_CLASSES': (
'rest_framework_yaml.renderers.YAMLRenderer',
),
}
</code></pre>
<h2 id="xml">XML</h2>
<p><a href="http://jpadilla.github.io/django-rest-framework-xml/">REST Framework XML</a> provides a simple informal XML format. It was previously included directly in the REST framework package, and is now instead supported as a third-party package.</p>
<h4 id="installation-configuration_1">Installation &amp; configuration</h4>
<p>Install using pip.</p>
<pre><code>$ pip install djangorestframework-xml
</code></pre>
<p>Modify your REST framework settings.</p>
<pre><code>REST_FRAMEWORK = {
'DEFAULT_PARSER_CLASSES': (
'rest_framework_xml.parsers.XMLParser',
),
'DEFAULT_RENDERER_CLASSES': (
'rest_framework_xml.renderers.XMLRenderer',
),
}
</code></pre>
<h2 id="messagepack">MessagePack</h2>
<p><a href="https://github.com/juanriaza/django-rest-framework-msgpack">MessagePack</a> is a fast, efficient binary serialization format. <a href="https://github.com/juanriaza">Juan Riaza</a> maintains the <a href="https://github.com/juanriaza/django-rest-framework-msgpack">djangorestframework-msgpack</a> package which provides MessagePack renderer and parser support for REST framework.</p>
<h2 id="camelcase-json">CamelCase JSON</h2>
......
api-guide/permissions/index.html
......@@ -189,6 +189,10 @@
</li>
<li >
<a href="../versioning">Versioning</a>
</li>
<li >
<a href="../content-negotiation">Content negotiation</a>
</li>
......@@ -232,6 +236,10 @@
</li>
<li >
<a href="../../topics/internationalization">Internationalization</a>
</li>
<li >
<a href="../../topics/ajax-csrf-cors">AJAX, CSRF & CORS</a>
</li>
......@@ -260,23 +268,11 @@
</li>
<li >
<a href="../../topics/rest-framework-2-announcement">2.0 Announcement</a>
</li>
<li >
<a href="../../topics/2.2-announcement">2.2 Announcement</a>
</li>
<li >
<a href="../../topics/2.3-announcement">2.3 Announcement</a>
</li>
<li >
<a href="../../topics/2.4-announcement">2.4 Announcement</a>
<a href="../../topics/3.0-announcement">3.0 Announcement</a>
</li>
<li >
<a href="../../topics/3.0-announcement">3.0 Announcement</a>
<a href="../../topics/3.1-announcement">3.1 Announcement</a>
</li>
<li >
......@@ -287,10 +283,6 @@
<a href="../../topics/release-notes">Release Notes</a>
</li>
<li >
<a href="../../topics/credits">Credits</a>
</li>
</ul>
</li>
......@@ -405,10 +397,6 @@
<a href="#djangoobjectpermissions">DjangoObjectPermissions</a>
</li>
<li>
<a href="#tokenhasreadwritescope">TokenHasReadWriteScope</a>
</li>
......@@ -575,16 +563,6 @@ def example_view(request, format=None):
<hr />
<p><strong>Note</strong>: If you need object level <code>view</code> permissions for <code>GET</code>, <code>HEAD</code> and <code>OPTIONS</code> requests, you'll want to consider also adding the <code>DjangoObjectPermissionsFilter</code> class to ensure that list endpoints only return results including objects for which the user has appropriate view permissions.</p>
<hr />
<h2 id="tokenhasreadwritescope">TokenHasReadWriteScope</h2>
<p>This permission class is intended for use with either of the <code>OAuthAuthentication</code> and <code>OAuth2Authentication</code> classes, and ties into the scoping that their backends provide.</p>
<p>Requests with a safe methods of <code>GET</code>, <code>OPTIONS</code> or <code>HEAD</code> will be allowed if the authenticated token has read permission.</p>
<p>Requests for <code>POST</code>, <code>PUT</code>, <code>PATCH</code> and <code>DELETE</code> will be allowed if the authenticated token has write permission.</p>
<p>This permission class relies on the implementations of the <a href="http://code.larlet.fr/django-oauth-plus">django-oauth-plus</a> and <a href="https://github.com/caffeinehit/django-oauth2-provider">django-oauth2-provider</a> libraries, which both provide limited support for controlling the scope of access tokens:</p>
<ul>
<li><code>django-oauth-plus</code>: Tokens are associated with a <code>Resource</code> class which has a <code>name</code>, <code>url</code> and <code>is_readonly</code> properties.</li>
<li><code>django-oauth2-provider</code>: Tokens are associated with a bitwise <code>scope</code> attribute, that defaults to providing bitwise values for <code>read</code> and/or <code>write</code>.</li>
</ul>
<p>If you require more advanced scoping for your API, such as restricting tokens to accessing a subset of functionality of your API then you will need to provide a custom permission class. See the source of the <code>django-oauth-plus</code> or <code>django-oauth2-provider</code> package for more details on scoping token access.</p>
<hr />
<h1 id="custom-permissions">Custom permissions</h1>
<p>To implement a custom permission, override <code>BasePermission</code> and implement either, or both, of the following methods:</p>
......
api-guide/relations/index.html
......@@ -189,6 +189,10 @@
</li>
<li >
<a href="../versioning">Versioning</a>
</li>
<li >
<a href="../content-negotiation">Content negotiation</a>
</li>
......@@ -232,6 +236,10 @@
</li>
<li >
<a href="../../topics/internationalization">Internationalization</a>
</li>
<li >
<a href="../../topics/ajax-csrf-cors">AJAX, CSRF & CORS</a>
</li>
......@@ -260,23 +268,11 @@
</li>
<li >
<a href="../../topics/rest-framework-2-announcement">2.0 Announcement</a>
</li>
<li >
<a href="../../topics/2.2-announcement">2.2 Announcement</a>
</li>
<li >
<a href="../../topics/2.3-announcement">2.3 Announcement</a>
</li>
<li >
<a href="../../topics/2.4-announcement">2.4 Announcement</a>
<a href="../../topics/3.0-announcement">3.0 Announcement</a>
</li>
<li >
<a href="../../topics/3.0-announcement">3.0 Announcement</a>
<a href="../../topics/3.1-announcement">3.1 Announcement</a>
</li>
<li >
......@@ -287,10 +283,6 @@
<a href="../../topics/release-notes">Release Notes</a>
</li>
<li >
<a href="../../topics/credits">Credits</a>
</li>
</ul>
</li>
......
api-guide/renderers/index.html
......@@ -189,6 +189,10 @@
</li>
<li >
<a href="../versioning">Versioning</a>
</li>
<li >
<a href="../content-negotiation">Content negotiation</a>
</li>
......@@ -232,6 +236,10 @@
</li>
<li >
<a href="../../topics/internationalization">Internationalization</a>
</li>
<li >
<a href="../../topics/ajax-csrf-cors">AJAX, CSRF & CORS</a>
</li>
......@@ -260,23 +268,11 @@
</li>
<li >
<a href="../../topics/rest-framework-2-announcement">2.0 Announcement</a>
</li>
<li >
<a href="../../topics/2.2-announcement">2.2 Announcement</a>
</li>
<li >
<a href="../../topics/2.3-announcement">2.3 Announcement</a>
</li>
<li >
<a href="../../topics/2.4-announcement">2.4 Announcement</a>
<a href="../../topics/3.0-announcement">3.0 Announcement</a>
</li>
<li >
<a href="../../topics/3.0-announcement">3.0 Announcement</a>
<a href="../../topics/3.1-announcement">3.1 Announcement</a>
</li>
<li >
......@@ -287,10 +283,6 @@
<a href="../../topics/release-notes">Release Notes</a>
</li>
<li >
<a href="../../topics/credits">Credits</a>
</li>
</ul>
</li>
......@@ -382,22 +374,6 @@
</li>
<li>
<a href="#jsonprenderer">JSONPRenderer</a>
</li>
<li>
<a href="#yamlrenderer">YAMLRenderer</a>
</li>
<li>
<a href="#unicodeyamlrenderer">UnicodeYAMLRenderer</a>
</li>
<li>
<a href="#xmlrenderer">XMLRenderer</a>
</li>
<li>
<a href="#templatehtmlrenderer">TemplateHTMLRenderer</a>
</li>
......@@ -478,6 +454,18 @@
<li>
<a href="#yaml">YAML</a>
</li>
<li>
<a href="#xml">XML</a>
</li>
<li>
<a href="#jsonp">JSONP</a>
</li>
<li>
<a href="#messagepack">MessagePack</a>
</li>
......@@ -527,10 +515,10 @@
<p>The basic process of content negotiation involves examining the request's <code>Accept</code> header, to determine which media types it expects in the response. Optionally, format suffixes on the URL may be used to explicitly request a particular representation. For example the URL <code>http://example.com/api/users_count.json</code> might be an endpoint that always returns JSON data.</p>
<p>For more information see the documentation on <a href="../content-negotiation">content negotiation</a>.</p>
<h2 id="setting-the-renderers">Setting the renderers</h2>
<p>The default set of renderers may be set globally, using the <code>DEFAULT_RENDERER_CLASSES</code> setting. For example, the following settings would use <code>YAML</code> as the main media type and also include the self describing API.</p>
<p>The default set of renderers may be set globally, using the <code>DEFAULT_RENDERER_CLASSES</code> setting. For example, the following settings would use <code>JSON</code> as the main media type and also include the self describing API.</p>
<pre><code>REST_FRAMEWORK = {
'DEFAULT_RENDERER_CLASSES': (
'rest_framework.renderers.YAMLRenderer',
'rest_framework.renderers.JSONRenderer',
'rest_framework.renderers.BrowsableAPIRenderer',
)
}
......@@ -538,15 +526,15 @@
<p>You can also set the renderers used for an individual view, or viewset,
using the <code>APIView</code> class based views.</p>
<pre><code>from django.contrib.auth.models import User
from rest_framework.renderers import JSONRenderer, YAMLRenderer
from rest_framework.renderers import JSONRenderer
from rest_framework.response import Response
from rest_framework.views import APIView
class UserCountView(APIView):
"""
A view that returns the count of active users, in JSON or YAML.
A view that returns the count of active users in JSON.
"""
renderer_classes = (JSONRenderer, YAMLRenderer)
renderer_classes = (JSONRenderer, )
def get(self, request, format=None):
user_count = User.objects.filter(active=True).count()
......@@ -555,10 +543,10 @@ class UserCountView(APIView):
</code></pre>
<p>Or, if you're using the <code>@api_view</code> decorator with function based views.</p>
<pre><code>@api_view(['GET'])
@renderer_classes((JSONRenderer, JSONPRenderer))
@renderer_classes((JSONRenderer,))
def user_count_view(request, format=None):
"""
A view that returns the count of active users, in JSON or JSONp.
A view that returns the count of active users in JSON.
"""
user_count = User.objects.filter(active=True).count()
content = {'user_count': user_count}
......@@ -585,41 +573,6 @@ def user_count_view(request, format=None):
<p><strong>.media_type</strong>: <code>application/json</code></p>
<p><strong>.format</strong>: <code>'.json'</code></p>
<p><strong>.charset</strong>: <code>None</code></p>
<h2 id="jsonprenderer">JSONPRenderer</h2>
<p>Renders the request data into <code>JSONP</code>. The <code>JSONP</code> media type provides a mechanism of allowing cross-domain AJAX requests, by wrapping a <code>JSON</code> response in a javascript callback.</p>
<p>The javascript callback function must be set by the client including a <code>callback</code> URL query parameter. For example <code>http://example.com/api/users?callback=jsonpCallback</code>. If the callback function is not explicitly set by the client it will default to <code>'callback'</code>.</p>
<hr />
<p><strong>Warning</strong>: If you require cross-domain AJAX requests, you should almost certainly be using the more modern approach of <a href="http://www.w3.org/TR/cors/">CORS</a> as an alternative to <code>JSONP</code>. See the <a href="../../topics/ajax-csrf-cors">CORS documentation</a> for more details.</p>
<p>The <code>jsonp</code> approach is essentially a browser hack, and is <a href="http://stackoverflow.com/questions/613962/is-jsonp-safe-to-use">only appropriate for globally readable API endpoints</a>, where <code>GET</code> requests are unauthenticated and do not require any user permissions.</p>
<hr />
<p><strong>.media_type</strong>: <code>application/javascript</code></p>
<p><strong>.format</strong>: <code>'.jsonp'</code></p>
<p><strong>.charset</strong>: <code>utf-8</code></p>
<h2 id="yamlrenderer">YAMLRenderer</h2>
<p>Renders the request data into <code>YAML</code>.</p>
<p>Requires the <code>pyyaml</code> package to be installed.</p>
<p>Note that non-ascii characters will be rendered using <code>\uXXXX</code> character escape. For example:</p>
<pre><code>unicode black star: "\u2605"
</code></pre>
<p><strong>.media_type</strong>: <code>application/yaml</code></p>
<p><strong>.format</strong>: <code>'.yaml'</code></p>
<p><strong>.charset</strong>: <code>utf-8</code></p>
<h2 id="unicodeyamlrenderer">UnicodeYAMLRenderer</h2>
<p>Renders the request data into <code>YAML</code>.</p>
<p>Requires the <code>pyyaml</code> package to be installed.</p>
<p>Note that non-ascii characters will not be character escaped. For example:</p>
<pre><code>unicode black star: ★
</code></pre>
<p><strong>.media_type</strong>: <code>application/yaml</code></p>
<p><strong>.format</strong>: <code>'.yaml'</code></p>
<p><strong>.charset</strong>: <code>utf-8</code></p>
<h2 id="xmlrenderer">XMLRenderer</h2>
<p>Renders REST framework's default style of <code>XML</code> response content.</p>
<p>Note that the <code>XML</code> markup language is used typically used as the base language for more strictly defined domain-specific languages, such as <code>RSS</code>, <code>Atom</code>, and <code>XHTML</code>.</p>
<p>If you are considering using <code>XML</code> for your API, you may want to consider implementing a custom renderer and parser for your specific requirements, and using an existing domain-specific media-type, or creating your own custom XML-based media-type.</p>
<p><strong>.media_type</strong>: <code>application/xml</code></p>
<p><strong>.format</strong>: <code>'.xml'</code></p>
<p><strong>.charset</strong>: <code>utf-8</code></p>
<h2 id="templatehtmlrenderer">TemplateHTMLRenderer</h2>
<p>Renders data to HTML, using Django's standard template rendering.
Unlike other renderers, the data passed to the <code>Response</code> does not need to be serialized. Also, unlike other renderers, you may want to include a <code>template_name</code> argument when creating the <code>Response</code>.</p>
......@@ -791,10 +744,59 @@ In this case you can underspecify the media types it should respond to, by using
<hr />
<h1 id="third-party-packages">Third party packages</h1>
<p>The following third party packages are also available.</p>
<h2 id="yaml">YAML</h2>
<p><a href="http://jpadilla.github.io/django-rest-framework-yaml/">REST framework YAML</a> provides <a href="http://www.yaml.org/">YAML</a> parsing and rendering support. It was previously included directly in the REST framework package, and is now instead supported as a third-party package.</p>
<h4 id="installation-configuration">Installation &amp; configuration</h4>
<p>Install using pip.</p>
<pre><code>$ pip install djangorestframework-yaml
</code></pre>
<p>Modify your REST framework settings.</p>
<pre><code>REST_FRAMEWORK = {
'DEFAULT_PARSER_CLASSES': (
'rest_framework_yaml.parsers.YAMLParser',
),
'DEFAULT_RENDERER_CLASSES': (
'rest_framework_yaml.renderers.YAMLRenderer',
),
}
</code></pre>
<h2 id="xml">XML</h2>
<p><a href="http://jpadilla.github.io/django-rest-framework-xml/">REST Framework XML</a> provides a simple informal XML format. It was previously included directly in the REST framework package, and is now instead supported as a third-party package.</p>
<h4 id="installation-configuration_1">Installation &amp; configuration</h4>
<p>Install using pip.</p>
<pre><code>$ pip install djangorestframework-xml
</code></pre>
<p>Modify your REST framework settings.</p>
<pre><code>REST_FRAMEWORK = {
'DEFAULT_PARSER_CLASSES': (
'rest_framework_xml.parsers.XMLParser',
),
'DEFAULT_RENDERER_CLASSES': (
'rest_framework_xml.renderers.XMLRenderer',
),
}
</code></pre>
<h2 id="jsonp">JSONP</h2>
<p><a href="http://jpadilla.github.io/django-rest-framework-jsonp/">REST framework JSONP</a> provides JSONP rendering support. It was previously included directly in the REST framework package, and is now instead supported as a third-party package.</p>
<hr />
<p><strong>Warning</strong>: If you require cross-domain AJAX requests, you should generally be using the more modern approach of <a href="http://www.w3.org/TR/cors/">CORS</a> as an alternative to <code>JSONP</code>. See the <a href="http://www.django-rest-framework.org/topics/ajax-csrf-cors/">CORS documentation</a> for more details.</p>
<p>The <code>jsonp</code> approach is essentially a browser hack, and is <a href="http://stackoverflow.com/questions/613962/is-jsonp-safe-to-use">only appropriate for globally readable API endpoints</a>, where <code>GET</code> requests are unauthenticated and do not require any user permissions.</p>
<hr />
<h4 id="installation-configuration_2">Installation &amp; configuration</h4>
<p>Install using pip.</p>
<pre><code>$ pip install djangorestframework-jsonp
</code></pre>
<p>Modify your REST framework settings.</p>
<pre><code>REST_FRAMEWORK = {
'DEFAULT_RENDERER_CLASSES': (
'rest_framework_yaml.renderers.JSONPRenderer',
),
}
</code></pre>
<h2 id="messagepack">MessagePack</h2>
<p><a href="http://msgpack.org/">MessagePack</a> is a fast, efficient binary serialization format. <a href="https://github.com/juanriaza">Juan Riaza</a> maintains the <a href="https://github.com/juanriaza/django-rest-framework-msgpack">djangorestframework-msgpack</a> package which provides MessagePack renderer and parser support for REST framework.</p>
<h2 id="csv">CSV</h2>
<p>Comma-separated values are a plain-text tabular data format, that can be easily imported into spreadsheet applications. <a href="https://github.com/mjumbewu">Mjumbe Poe</a> maintains the <a href="https://github.com/mjumbewu/django-rest-framework-csv">djangorestframework-csv</a> package which provides CSV renderer support for REST framework.</p>
<p>Comma-separated values are a plain-text tabular data format, that can be easily imported into spreadsheet applications. <a href="https://github.com/mjumbewu">Mjumbe Poe</a> maintains the <a href="https://github.com/mjumbewu/django-rest-framework-csv">djangorestframework-csv</a> package which provides CSV renderer support for REST framework.</p>
<h2 id="ultrajson">UltraJSON</h2>
<p><a href="https://github.com/esnme/ultrajson">UltraJSON</a> is an optimized C JSON encoder which can give significantly faster JSON rendering. <a href="https://github.com/hzy">Jacob Haslehurst</a> maintains the <a href="https://github.com/gizmag/drf-ujson-renderer">drf-ujson-renderer</a> package which implements JSON rendering using the UJSON package.</p>
<h2 id="camelcase-json">CamelCase JSON</h2>
......
api-guide/requests/index.html
......@@ -189,6 +189,10 @@
</li>
<li >
<a href="../versioning">Versioning</a>
</li>
<li >
<a href="../content-negotiation">Content negotiation</a>
</li>
......@@ -232,6 +236,10 @@
</li>
<li >
<a href="../../topics/internationalization">Internationalization</a>
</li>
<li >
<a href="../../topics/ajax-csrf-cors">AJAX, CSRF & CORS</a>
</li>
......@@ -260,23 +268,11 @@
</li>
<li >
<a href="../../topics/rest-framework-2-announcement">2.0 Announcement</a>
</li>
<li >
<a href="../../topics/2.2-announcement">2.2 Announcement</a>
</li>
<li >
<a href="../../topics/2.3-announcement">2.3 Announcement</a>
</li>
<li >
<a href="../../topics/2.4-announcement">2.4 Announcement</a>
<a href="../../topics/3.0-announcement">3.0 Announcement</a>
</li>
<li >
<a href="../../topics/3.0-announcement">3.0 Announcement</a>
<a href="../../topics/3.1-announcement">3.1 Announcement</a>
</li>
<li >
......@@ -287,10 +283,6 @@
<a href="../../topics/release-notes">Release Notes</a>
</li>
<li >
<a href="../../topics/credits">Credits</a>
</li>
</ul>
</li>
......@@ -492,7 +484,7 @@
<p><code>request.query_params</code> is a more correctly named synonym for <code>request.GET</code>.</p>
<p>For clarity inside your code, we recommend using <code>request.query_params</code> instead of the Django's standard <code>request.GET</code>. Doing so will help keep your codebase more correct and obvious - any HTTP method type may include query parameters, not just <code>GET</code> requests.</p>
<h2 id="data-and-files">.DATA and .FILES</h2>
<p>The old-style version 2.x <code>request.data</code> and <code>request.FILES</code> attributes are still available, but are now pending deprecation in favor of the unified <code>request.data</code> attribute.</p>
<p>The old-style version 2.x <code>request.DATA</code> and <code>request.FILES</code> attributes are still available, but are now pending deprecation in favor of the unified <code>request.data</code> attribute.</p>
<h2 id="query_params_1">.QUERY_PARAMS</h2>
<p>The old-style version 2.x <code>request.QUERY_PARAMS</code> attribute is still available, but is now pending deprecation in favor of the more pythonic <code>request.query_params</code>.</p>
<h2 id="parsers">.parsers</h2>
......
api-guide/responses/index.html
......@@ -189,6 +189,10 @@
</li>
<li >
<a href="../versioning">Versioning</a>
</li>
<li >
<a href="../content-negotiation">Content negotiation</a>
</li>
......@@ -232,6 +236,10 @@
</li>
<li >
<a href="../../topics/internationalization">Internationalization</a>
</li>
<li >
<a href="../../topics/ajax-csrf-cors">AJAX, CSRF & CORS</a>
</li>
......@@ -260,23 +268,11 @@
</li>
<li >
<a href="../../topics/rest-framework-2-announcement">2.0 Announcement</a>
</li>
<li >
<a href="../../topics/2.2-announcement">2.2 Announcement</a>
</li>
<li >
<a href="../../topics/2.3-announcement">2.3 Announcement</a>
</li>
<li >
<a href="../../topics/2.4-announcement">2.4 Announcement</a>
<a href="../../topics/3.0-announcement">3.0 Announcement</a>
</li>
<li >
<a href="../../topics/3.0-announcement">3.0 Announcement</a>
<a href="../../topics/3.1-announcement">3.1 Announcement</a>
</li>
<li >
......@@ -287,10 +283,6 @@
<a href="../../topics/release-notes">Release Notes</a>
</li>
<li >
<a href="../../topics/credits">Credits</a>
</li>
</ul>
</li>
......
api-guide/reverse/index.html
......@@ -189,6 +189,10 @@
</li>
<li >
<a href="../versioning">Versioning</a>
</li>
<li >
<a href="../content-negotiation">Content negotiation</a>
</li>
......@@ -232,6 +236,10 @@
</li>
<li >
<a href="../../topics/internationalization">Internationalization</a>
</li>
<li >
<a href="../../topics/ajax-csrf-cors">AJAX, CSRF & CORS</a>
</li>
......@@ -260,23 +268,11 @@
</li>
<li >
<a href="../../topics/rest-framework-2-announcement">2.0 Announcement</a>
</li>
<li >
<a href="../../topics/2.2-announcement">2.2 Announcement</a>
</li>
<li >
<a href="../../topics/2.3-announcement">2.3 Announcement</a>
</li>
<li >
<a href="../../topics/2.4-announcement">2.4 Announcement</a>
<a href="../../topics/3.0-announcement">3.0 Announcement</a>
</li>
<li >
<a href="../../topics/3.0-announcement">3.0 Announcement</a>
<a href="../../topics/3.1-announcement">3.1 Announcement</a>
</li>
<li >
......@@ -287,10 +283,6 @@
<a href="../../topics/release-notes">Release Notes</a>
</li>
<li >
<a href="../../topics/credits">Credits</a>
</li>
</ul>
</li>
......
api-guide/routers/index.html
......@@ -189,6 +189,10 @@
</li>
<li >
<a href="../versioning">Versioning</a>
</li>
<li >
<a href="../content-negotiation">Content negotiation</a>
</li>
......@@ -232,6 +236,10 @@
</li>
<li >
<a href="../../topics/internationalization">Internationalization</a>
</li>
<li >
<a href="../../topics/ajax-csrf-cors">AJAX, CSRF & CORS</a>
</li>
......@@ -260,23 +268,11 @@
</li>
<li >
<a href="../../topics/rest-framework-2-announcement">2.0 Announcement</a>
</li>
<li >
<a href="../../topics/2.2-announcement">2.2 Announcement</a>
</li>
<li >
<a href="../../topics/2.3-announcement">2.3 Announcement</a>
</li>
<li >
<a href="../../topics/2.4-announcement">2.4 Announcement</a>
<a href="../../topics/3.0-announcement">3.0 Announcement</a>
</li>
<li >
<a href="../../topics/3.0-announcement">3.0 Announcement</a>
<a href="../../topics/3.1-announcement">3.1 Announcement</a>
</li>
<li >
......@@ -287,10 +283,6 @@
<a href="../../topics/release-notes">Release Notes</a>
</li>
<li >
<a href="../../topics/credits">Credits</a>
</li>
</ul>
</li>
......
api-guide/serializers/index.html
......@@ -189,6 +189,10 @@
</li>
<li >
<a href="../versioning">Versioning</a>
</li>
<li >
<a href="../content-negotiation">Content negotiation</a>
</li>
......@@ -232,6 +236,10 @@
</li>
<li >
<a href="../../topics/internationalization">Internationalization</a>
</li>
<li >
<a href="../../topics/ajax-csrf-cors">AJAX, CSRF & CORS</a>
</li>
......@@ -260,23 +268,11 @@
</li>
<li >
<a href="../../topics/rest-framework-2-announcement">2.0 Announcement</a>
</li>
<li >
<a href="../../topics/2.2-announcement">2.2 Announcement</a>
</li>
<li >
<a href="../../topics/2.3-announcement">2.3 Announcement</a>
</li>
<li >
<a href="../../topics/2.4-announcement">2.4 Announcement</a>
<a href="../../topics/3.0-announcement">3.0 Announcement</a>
</li>
<li >
<a href="../../topics/3.0-announcement">3.0 Announcement</a>
<a href="../../topics/3.1-announcement">3.1 Announcement</a>
</li>
<li >
......@@ -287,10 +283,6 @@
<a href="../../topics/release-notes">Release Notes</a>
</li>
<li >
<a href="../../topics/credits">Credits</a>
</li>
</ul>
</li>
......@@ -414,7 +406,7 @@
</li>
<li>
<a href="#specifying-which-fields-should-be-included">Specifying which fields should be included</a>
<a href="#specifying-which-fields-to-include">Specifying which fields to include</a>
</li>
<li>
......@@ -426,11 +418,11 @@
</li>
<li>
<a href="#specifying-which-fields-should-be-read-only">Specifying which fields should be read-only</a>
<a href="#specifying-read-only-fields">Specifying read only fields</a>
</li>
<li>
<a href="#specifying-additional-keyword-arguments-for-fields">Specifying additional keyword arguments for fields.</a>
<a href="#additional-keyword-arguments">Additional keyword arguments</a>
</li>
<li>
......@@ -441,6 +433,10 @@
<a href="#inheritance-of-the-meta-class">Inheritance of the 'Meta' class</a>
</li>
<li>
<a href="#customizing-field-mappings">Customizing field mappings</a>
</li>
......@@ -920,7 +916,7 @@ AccountSerializer():
name = CharField(allow_blank=True, max_length=100, required=False)
owner = PrimaryKeyRelatedField(queryset=User.objects.all())
</code></pre>
<h2 id="specifying-which-fields-should-be-included">Specifying which fields should be included</h2>
<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>For example:</p>
<pre><code>class AccountSerializer(serializers.ModelSerializer):
......@@ -950,7 +946,7 @@ AccountSerializer():
model = Account
</code></pre>
<p>Extra fields can correspond to any property or callable on the model.</p>
<h2 id="specifying-which-fields-should-be-read-only">Specifying which fields should be read-only</h2>
<h2 id="specifying-read-only-fields">Specifying read only fields</h2>
<p>You may wish to specify multiple fields as read-only. Instead of adding each field explicitly with the <code>read_only=True</code> attribute, you may use the shortcut Meta option, <code>read_only_fields</code>.</p>
<p>This option should be a list or tuple of field names, and is declared as follows:</p>
<pre><code>class AccountSerializer(serializers.ModelSerializer):
......@@ -968,7 +964,7 @@ AccountSerializer():
</code></pre>
<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="specifying-additional-keyword-arguments-for-fields">Specifying additional keyword arguments for fields.</h2>
<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>This option is a dictionary, mapping field names to a dictionary of keyword arguments. For example:</p>
<pre><code>class CreateUserSerializer(serializers.ModelSerializer):
......@@ -997,6 +993,43 @@ AccountSerializer():
model = Account
</code></pre>
<p>Typically we would recommend <em>not</em> using inheritance on inner Meta classes, but instead declaring all options explicitly.</p>
<h2 id="customizing-field-mappings">Customizing field mappings</h2>
<p>The ModelSerializer class also exposes an API that you can override in order to alter how serializer fields are automatically determined when instantiating the serializer.</p>
<p>Normally if a <code>ModelSerializer</code> does not generate the fields you need by default the you should either add them to the class explicitly, or simply use a regular <code>Serializer</code> class instead. However in some cases you may want to create a new base class that defines how the serializer fields are created for any given model.</p>
<h3 id="serializer_field_mapping"><code>.serializer_field_mapping</code></h3>
<p>A mapping of Django model classes to REST framework serializer classes. You can override this mapping to alter the default serializer classes that should be used for each model class.</p>
<h3 id="serializer_related_field"><code>.serializer_related_field</code></h3>
<p>This property should be the serializer field class, that is used for relational fields by default.</p>
<p>For <code>ModelSerializer</code> this defaults to <code>PrimaryKeyRelatedField</code>.</p>
<p>For <code>HyperlinkedModelSerializer</code> this defaults to <code>serializers.HyperlinkedRelatedField</code>.</p>
<h3 id="serializer_url_field"><code>serializer_url_field</code></h3>
<p>The serializer field class that should be used for any <code>url</code> field on the serializer.</p>
<p>Defaults to <code>serializers.HyperlinkedIdentityField</code></p>
<h3 id="serializer_choice_field"><code>serializer_choice_field</code></h3>
<p>The serializer field class that should be used for any choice fields on the serializer.</p>
<p>Defaults to <code>serializers.ChoiceField</code></p>
<h3 id="the-field_class-and-field_kwargs-api">The field_class and field_kwargs API</h3>
<p>The following methods are called to determine the class and keyword arguments for each field that should be automatically included on the serializer. Each of these methods should return a two tuple of <code>(field_class, field_kwargs)</code>.</p>
<h3 id="build_standard_fieldself-field_name-model_field"><code>.build_standard_field(self, field_name, model_field)</code></h3>
<p>Called to generate a serializer field that maps to a standard model field.</p>
<p>The default implementation returns a serializer class based on the <code>serializer_field_mapping</code> attribute.</p>
<h3 id="build_relational_fieldself-field_name-relation_info"><code>.build_relational_field(self, field_name, relation_info)</code></h3>
<p>Called to generate a serializer field that maps to a relational model field.</p>
<p>The default implementation returns a serializer class based on the <code>serializer_relational_field</code> attribute.</p>
<p>The <code>relation_info</code> argument is a named tuple, that contains <code>model_field</code>, <code>related_model</code>, <code>to_many</code> and <code>has_through_model</code> properties.</p>
<h3 id="build_nested_fieldself-field_name-relation_info-nested_depth"><code>.build_nested_field(self, field_name, relation_info, nested_depth)</code></h3>
<p>Called to generate a serializer field that maps to a relational model field, when the <code>depth</code> option has been set.</p>
<p>The default implementation dynamically creates a nested serializer class based on either <code>ModelSerializer</code> or <code>HyperlinkedModelSerializer</code>.</p>
<p>The <code>nested_depth</code> will be the value of the <code>depth</code> option, minus one.</p>
<p>The <code>relation_info</code> argument is a named tuple, that contains <code>model_field</code>, <code>related_model</code>, <code>to_many</code> and <code>has_through_model</code> properties.</p>
<h3 id="build_property_fieldself-field_name-model_class"><code>.build_property_field(self, field_name, model_class)</code></h3>
<p>Called to generate a serializer field that maps to a property or zero-argument method on the model class.</p>
<p>The default implementation returns a <code>ReadOnlyField</code> class.</p>
<h3 id="build_url_fieldself-field_name-model_class"><code>.build_url_field(self, field_name, model_class)</code></h3>
<p>Called to generate a serializer field for the serializer's own <code>url</code> field. The default implementation returns a <code>HyperlinkedIdentityField</code> class.</p>
<h3 id="build_unknown_fieldself-field_name-model_class"><code>.build_unknown_field(self, field_name, model_class)</code></h3>
<p>Called when the field name did not map to any model field or model property.
The default implementation raises an error, although subclasses may customize this behavior.</p>
<hr />
<h1 id="hyperlinkedmodelserializer">HyperlinkedModelSerializer</h1>
<p>The <code>HyperlinkedModelSerializer</code> class is similar to the <code>ModelSerializer</code> class except that it uses hyperlinks to represent relationships, rather than primary keys.</p>
......
api-guide/settings/index.html
......@@ -189,6 +189,10 @@
</li>
<li >
<a href="../versioning">Versioning</a>
</li>
<li >
<a href="../content-negotiation">Content negotiation</a>
</li>
......@@ -232,6 +236,10 @@
</li>
<li >
<a href="../../topics/internationalization">Internationalization</a>
</li>
<li >
<a href="../../topics/ajax-csrf-cors">AJAX, CSRF & CORS</a>
</li>
......@@ -260,23 +268,11 @@
</li>
<li >
<a href="../../topics/rest-framework-2-announcement">2.0 Announcement</a>
</li>
<li >
<a href="../../topics/2.2-announcement">2.2 Announcement</a>
</li>
<li >
<a href="../../topics/2.3-announcement">2.3 Announcement</a>
</li>
<li >
<a href="../../topics/2.4-announcement">2.4 Announcement</a>
<a href="../../topics/3.0-announcement">3.0 Announcement</a>
</li>
<li >
<a href="../../topics/3.0-announcement">3.0 Announcement</a>
<a href="../../topics/3.1-announcement">3.1 Announcement</a>
</li>
<li >
......@@ -287,10 +283,6 @@
<a href="../../topics/release-notes">Release Notes</a>
</li>
<li >
<a href="../../topics/credits">Credits</a>
</li>
</ul>
</li>
......@@ -378,6 +370,10 @@
</li>
<li>
<a href="#versioning-settings">Versioning settings</a>
</li>
<li>
<a href="#authentication-settings">Authentication settings</a>
</li>
......@@ -433,10 +429,10 @@
<p>For example your project's <code>settings.py</code> file might include something like this:</p>
<pre><code>REST_FRAMEWORK = {
'DEFAULT_RENDERER_CLASSES': (
'rest_framework.renderers.YAMLRenderer',
'rest_framework.renderers.JSONRenderer',
),
'DEFAULT_PARSER_CLASSES': (
'rest_framework.parsers.YAMLParser',
'rest_framework.parsers.JSONParser',
)
}
</code></pre>
......@@ -534,6 +530,17 @@ If set to <code>None</code> then generic filtering is disabled.</p>
<p>The name of a query parameter, which can be used to specify the ordering of results returned by <code>OrderingFilter</code>.</p>
<p>Default: <code>ordering</code></p>
<hr />
<h2 id="versioning-settings">Versioning settings</h2>
<h4 id="default_version">DEFAULT_VERSION</h4>
<p>The value that should be used for <code>request.version</code> when no versioning information is present.</p>
<p>Default: <code>None</code></p>
<h4 id="allowed_versions">ALLOWED_VERSIONS</h4>
<p>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.</p>
<p>Default: <code>None</code></p>
<h4 id="version_parameter">VERSION_PARAMETER</h4>
<p>The string that should used for any versioning parameters, such as in the media type or URL query parameters.</p>
<p>Default: <code>'version'</code></p>
<hr />
<h2 id="authentication-settings">Authentication settings</h2>
<p><em>The following settings control the behavior of unauthenticated requests.</em></p>
<h4 id="unauthenticated_user">UNAUTHENTICATED_USER</h4>
......@@ -661,7 +668,7 @@ If set to <code>None</code> then generic filtering is disabled.</p>
<p>A string representing the function that should be used when returning a response for any given exception. If the function returns <code>None</code>, a 500 error will be raised.</p>
<p>This setting can be changed to support error responses other than the default <code>{"detail": "Failure..."}</code> responses. For example, you can use it to provide API responses like <code>{"errors": [{"message": "Failure...", "code": ""} ...]}</code>.</p>
<p>This should be a function with the following signature:</p>
<pre><code>exception_handler(exc)
<pre><code>exception_handler(exc, context)
</code></pre>
<ul>
<li><code>exc</code>: The exception.</li>
......
api-guide/status-codes/index.html
......@@ -189,6 +189,10 @@
</li>
<li >
<a href="../versioning">Versioning</a>
</li>
<li >
<a href="../content-negotiation">Content negotiation</a>
</li>
......@@ -232,6 +236,10 @@
</li>
<li >
<a href="../../topics/internationalization">Internationalization</a>
</li>
<li >
<a href="../../topics/ajax-csrf-cors">AJAX, CSRF & CORS</a>
</li>
......@@ -260,23 +268,11 @@
</li>
<li >
<a href="../../topics/rest-framework-2-announcement">2.0 Announcement</a>
</li>
<li >
<a href="../../topics/2.2-announcement">2.2 Announcement</a>
</li>
<li >
<a href="../../topics/2.3-announcement">2.3 Announcement</a>
</li>
<li >
<a href="../../topics/2.4-announcement">2.4 Announcement</a>
<a href="../../topics/3.0-announcement">3.0 Announcement</a>
</li>
<li >
<a href="../../topics/3.0-announcement">3.0 Announcement</a>
<a href="../../topics/3.1-announcement">3.1 Announcement</a>
</li>
<li >
......@@ -287,10 +283,6 @@
<a href="../../topics/release-notes">Release Notes</a>
</li>
<li >
<a href="../../topics/credits">Credits</a>
</li>
</ul>
</li>
......
api-guide/testing/index.html
......@@ -189,6 +189,10 @@
</li>
<li >
<a href="../versioning">Versioning</a>
</li>
<li >
<a href="../content-negotiation">Content negotiation</a>
</li>
......@@ -232,6 +236,10 @@
</li>
<li >
<a href="../../topics/internationalization">Internationalization</a>
</li>
<li >
<a href="../../topics/ajax-csrf-cors">AJAX, CSRF & CORS</a>
</li>
......@@ -260,23 +268,11 @@
</li>
<li >
<a href="../../topics/rest-framework-2-announcement">2.0 Announcement</a>
</li>
<li >
<a href="../../topics/2.2-announcement">2.2 Announcement</a>
</li>
<li >
<a href="../../topics/2.3-announcement">2.3 Announcement</a>
</li>
<li >
<a href="../../topics/2.4-announcement">2.4 Announcement</a>
<a href="../../topics/3.0-announcement">3.0 Announcement</a>
</li>
<li >
<a href="../../topics/3.0-announcement">3.0 Announcement</a>
<a href="../../topics/3.1-announcement">3.1 Announcement</a>
</li>
<li >
......@@ -287,10 +283,6 @@
<a href="../../topics/release-notes">Release Notes</a>
</li>
<li >
<a href="../../topics/credits">Credits</a>
</li>
</ul>
</li>
......@@ -469,7 +461,7 @@
<h1 id="apirequestfactory">APIRequestFactory</h1>
<p>Extends <a href="https://docs.djangoproject.com/en/dev/topics/testing/advanced/#django.test.client.RequestFactory">Django's existing <code>RequestFactory</code> class</a>.</p>
<h2 id="creating-test-requests">Creating test requests</h2>
<p>The <code>APIRequestFactory</code> class supports an almost identical API to Django's standard <code>RequestFactory</code> class. This means the that standard <code>.get()</code>, <code>.post()</code>, <code>.put()</code>, <code>.patch()</code>, <code>.delete()</code>, <code>.head()</code> and <code>.options()</code> methods are all available.</p>
<p>The <code>APIRequestFactory</code> class supports an almost identical API to Django's standard <code>RequestFactory</code> class. This means that the standard <code>.get()</code>, <code>.post()</code>, <code>.put()</code>, <code>.patch()</code>, <code>.delete()</code>, <code>.head()</code> and <code>.options()</code> methods are all available.</p>
<pre><code>from rest_framework.test import APIRequestFactory
# Using the standard RequestFactory API to create a form POST request
......@@ -506,7 +498,9 @@ request = factory.put('/notes/547/', content, content_type=content_type)
<h2 id="forcing-authentication">Forcing authentication</h2>
<p>When testing views directly using a request factory, it's often convenient to be able to directly authenticate the request, rather than having to construct the correct authentication credentials.</p>
<p>To forcibly authenticate a request, use the <code>force_authenticate()</code> method.</p>
<pre><code>factory = APIRequestFactory()
<pre><code>from rest_framework.tests import force_authenticate
factory = APIRequestFactory()
user = User.objects.get(username='olivia')
view = AccountDetail.as_view()
......@@ -538,9 +532,9 @@ response = view(request)
<p><strong>Note</strong>: It's worth noting that Django's standard <code>RequestFactory</code> doesn't need to include this option, because when using regular Django the CSRF validation takes place in middleware, which is not run when testing views directly. When using REST framework, CSRF validation takes place inside the view, so the request factory needs to disable view-level CSRF checks.</p>
<hr />
<h1 id="apiclient">APIClient</h1>
<p>Extends <a href="https://docs.djangoproject.com/en/dev/topics/testing/overview/#module-django.test.client">Django's existing <code>Client</code> class</a>.</p>
<p>Extends <a href="https://docs.djangoproject.com/en/dev/topics/testing/tools/#the-test-client">Django's existing <code>Client</code> class</a>.</p>
<h2 id="making-requests">Making requests</h2>
<p>The <code>APIClient</code> class supports the same request interface as <code>APIRequestFactory</code>. This means the that standard <code>.get()</code>, <code>.post()</code>, <code>.put()</code>, <code>.patch()</code>, <code>.delete()</code>, <code>.head()</code> and <code>.options()</code> methods are all available. For example:</p>
<p>The <code>APIClient</code> class supports the same request interface as Django's standard <code>Client</code> class. This means the that standard <code>.get()</code>, <code>.post()</code>, <code>.put()</code>, <code>.patch()</code>, <code>.delete()</code>, <code>.head()</code> and <code>.options()</code> methods are all available. For example:</p>
<pre><code>from rest_framework.test import APIClient
client = APIClient()
......@@ -646,13 +640,13 @@ self.assertEqual(response.content, '{"username": "lauren", "id": 4}')
</code></pre>
<h2 id="setting-the-available-formats">Setting the available formats</h2>
<p>If you need to test requests using something other than multipart or json requests, you can do so by setting the <code>TEST_REQUEST_RENDERER_CLASSES</code> setting.</p>
<p>For example, to add support for using <code>format='yaml'</code> in test requests, you might have something like this in your <code>settings.py</code> file.</p>
<p>For example, to add support for using <code>format='html'</code> in test requests, you might have something like this in your <code>settings.py</code> file.</p>
<pre><code>REST_FRAMEWORK = {
...
'TEST_REQUEST_RENDERER_CLASSES': (
'rest_framework.renderers.MultiPartRenderer',
'rest_framework.renderers.JSONRenderer',
'rest_framework.renderers.YAMLRenderer'
'rest_framework.renderers.TemplateHTMLRenderer'
)
}
</code></pre>
......
api-guide/throttling/index.html
......@@ -189,6 +189,10 @@
</li>
<li >
<a href="../versioning">Versioning</a>
</li>
<li >
<a href="../content-negotiation">Content negotiation</a>
</li>
......@@ -232,6 +236,10 @@
</li>
<li >
<a href="../../topics/internationalization">Internationalization</a>
</li>
<li >
<a href="../../topics/ajax-csrf-cors">AJAX, CSRF & CORS</a>
</li>
......@@ -260,23 +268,11 @@
</li>
<li >
<a href="../../topics/rest-framework-2-announcement">2.0 Announcement</a>
</li>
<li >
<a href="../../topics/2.2-announcement">2.2 Announcement</a>
</li>
<li >
<a href="../../topics/2.3-announcement">2.3 Announcement</a>
</li>
<li >
<a href="../../topics/2.4-announcement">2.4 Announcement</a>
<a href="../../topics/3.0-announcement">3.0 Announcement</a>
</li>
<li >
<a href="../../topics/3.0-announcement">3.0 Announcement</a>
<a href="../../topics/3.1-announcement">3.1 Announcement</a>
</li>
<li >
......@@ -287,10 +283,6 @@
<a href="../../topics/release-notes">Release Notes</a>
</li>
<li >
<a href="../../topics/credits">Credits</a>
</li>
</ul>
</li>
......
api-guide/validators/index.html
......@@ -189,6 +189,10 @@
</li>
<li >
<a href="../versioning">Versioning</a>
</li>
<li >
<a href="../content-negotiation">Content negotiation</a>
</li>
......@@ -232,6 +236,10 @@
</li>
<li >
<a href="../../topics/internationalization">Internationalization</a>
</li>
<li >
<a href="../../topics/ajax-csrf-cors">AJAX, CSRF & CORS</a>
</li>
......@@ -260,23 +268,11 @@
</li>
<li >
<a href="../../topics/rest-framework-2-announcement">2.0 Announcement</a>
</li>
<li >
<a href="../../topics/2.2-announcement">2.2 Announcement</a>
</li>
<li >
<a href="../../topics/2.3-announcement">2.3 Announcement</a>
</li>
<li >
<a href="../../topics/2.4-announcement">2.4 Announcement</a>
<a href="../../topics/3.0-announcement">3.0 Announcement</a>
</li>
<li >
<a href="../../topics/3.0-announcement">3.0 Announcement</a>
<a href="../../topics/3.1-announcement">3.1 Announcement</a>
</li>
<li >
......@@ -287,10 +283,6 @@
<a href="../../topics/release-notes">Release Notes</a>
</li>
<li >
<a href="../../topics/credits">Credits</a>
</li>
</ul>
</li>
......
topics/2.2-announcement/index.html → api-guide/versioning/index.html
......@@ -4,11 +4,11 @@
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta charset="utf-8">
<title>2.2 Announcement - Django REST framework</title>
<title>Versioning - 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/2.2-announcement/" />
<link rel="canonical" href="http://www.django-rest-framework.org/api-guide/versioning/" />
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="description" content="Django, API, REST, 2.2 Announcement">
<meta name="description" content="Django, API, REST, Versioning">
<meta name="author" content="Tom Christie">
<!-- Le styles -->
......@@ -62,10 +62,10 @@
<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="../2.3-announcement">
<a class="repo-link btn btn-inverse btn-small " rel="prev" href="../content-negotiation">
Next <i class="icon-arrow-right icon-white"></i>
</a>
<a class="repo-link btn btn-inverse btn-small " rel="next" href="../rest-framework-2-announcement">
<a class="repo-link btn btn-inverse btn-small " rel="next" href="../pagination">
<i class="icon-arrow-left icon-white"></i> Previous
</a>
<a class="repo-link btn btn-inverse btn-small" href="#searchModal" data-toggle="modal"><i class="icon-search icon-white"></i> Search</a>
......@@ -116,179 +116,171 @@
</ul>
</li>
<li class="dropdown">
<li class="dropdown active">
<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>
<a href="../requests">Requests</a>
</li>
<li >
<a href="../../api-guide/responses">Responses</a>
<a href="../responses">Responses</a>
</li>
<li >
<a href="../../api-guide/views">Views</a>
<a href="../views">Views</a>
</li>
<li >
<a href="../../api-guide/generic-views">Generic views</a>
<a href="../generic-views">Generic views</a>
</li>
<li >
<a href="../../api-guide/viewsets">Viewsets</a>
<a href="../viewsets">Viewsets</a>
</li>
<li >
<a href="../../api-guide/routers">Routers</a>
<a href="../routers">Routers</a>
</li>
<li >
<a href="../../api-guide/parsers">Parsers</a>
<a href="../parsers">Parsers</a>
</li>
<li >
<a href="../../api-guide/renderers">Renderers</a>
<a href="../renderers">Renderers</a>
</li>
<li >
<a href="../../api-guide/serializers">Serializers</a>
<a href="../serializers">Serializers</a>
</li>
<li >
<a href="../../api-guide/fields">Serializer fields</a>
<a href="../fields">Serializer fields</a>
</li>
<li >
<a href="../../api-guide/relations">Serializer relations</a>
<a href="../relations">Serializer relations</a>
</li>
<li >
<a href="../../api-guide/validators">Validators</a>
<a href="../validators">Validators</a>
</li>
<li >
<a href="../../api-guide/authentication">Authentication</a>
<a href="../authentication">Authentication</a>
</li>
<li >
<a href="../../api-guide/permissions">Permissions</a>
<a href="../permissions">Permissions</a>
</li>
<li >
<a href="../../api-guide/throttling">Throttling</a>
<a href="../throttling">Throttling</a>
</li>
<li >
<a href="../../api-guide/filtering">Filtering</a>
<a href="../filtering">Filtering</a>
</li>
<li >
<a href="../../api-guide/pagination">Pagination</a>
<a href="../pagination">Pagination</a>
</li>
<li class="active" >
<a href=".">Versioning</a>
</li>
<li >
<a href="../../api-guide/content-negotiation">Content negotiation</a>
<a href="../content-negotiation">Content negotiation</a>
</li>
<li >
<a href="../../api-guide/metadata">Metadata</a>
<a href="../metadata">Metadata</a>
</li>
<li >
<a href="../../api-guide/format-suffixes">Format suffixes</a>
<a href="../format-suffixes">Format suffixes</a>
</li>
<li >
<a href="../../api-guide/reverse">Returning URLs</a>
<a href="../reverse">Returning URLs</a>
</li>
<li >
<a href="../../api-guide/exceptions">Exceptions</a>
<a href="../exceptions">Exceptions</a>
</li>
<li >
<a href="../../api-guide/status-codes">Status codes</a>
<a href="../status-codes">Status codes</a>
</li>
<li >
<a href="../../api-guide/testing">Testing</a>
<a href="../testing">Testing</a>
</li>
<li >
<a href="../../api-guide/settings">Settings</a>
<a href="../settings">Settings</a>
</li>
</ul>
</li>
<li class="dropdown active">
<li class="dropdown">
<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>
<a href="../../topics/documenting-your-api">Documenting your API</a>
</li>
<li >
<a href="../ajax-csrf-cors">AJAX, CSRF & CORS</a>
<a href="../../topics/internationalization">Internationalization</a>
</li>
<li >
<a href="../browser-enhancements">Browser enhancements</a>
<a href="../../topics/ajax-csrf-cors">AJAX, CSRF & CORS</a>
</li>
<li >
<a href="../browsable-api">The Browsable API</a>
<a href="../../topics/browser-enhancements">Browser enhancements</a>
</li>
<li >
<a href="../rest-hypermedia-hateoas">REST, Hypermedia & HATEOAS</a>
<a href="../../topics/browsable-api">The Browsable API</a>
</li>
<li >
<a href="../third-party-resources">Third Party Resources</a>
<a href="../../topics/rest-hypermedia-hateoas">REST, Hypermedia & HATEOAS</a>
</li>
<li >
<a href="../contributing">Contributing to REST framework</a>
<a href="../../topics/third-party-resources">Third Party Resources</a>
</li>
<li >
<a href="../project-management">Project management</a>
<a href="../../topics/contributing">Contributing to REST framework</a>
</li>
<li >
<a href="../rest-framework-2-announcement">2.0 Announcement</a>
</li>
<li class="active" >
<a href=".">2.2 Announcement</a>
<a href="../../topics/project-management">Project management</a>
</li>
<li >
<a href="../2.3-announcement">2.3 Announcement</a>
<a href="../../topics/3.0-announcement">3.0 Announcement</a>
</li>
<li >
<a href="../2.4-announcement">2.4 Announcement</a>
<a href="../../topics/3.1-announcement">3.1 Announcement</a>
</li>
<li >
<a href="../3.0-announcement">3.0 Announcement</a>
<a href="../../topics/kickstarter-announcement">Kickstarter Announcement</a>
</li>
<li >
<a href="../kickstarter-announcement">Kickstarter Announcement</a>
</li>
<li >
<a href="../release-notes">Release Notes</a>
</li>
<li >
<a href="../credits">Credits</a>
<a href="../../topics/release-notes">Release Notes</a>
</li>
</ul>
......@@ -353,24 +345,56 @@
<li class="main">
<a href="#django-rest-framework-22">Django REST framework 2.2</a>
<a href="#versioning">Versioning</a>
</li>
<li>
<a href="#versioning-with-rest-framework">Versioning with REST framework</a>
</li>
<li>
<a href="#configuring-the-versioning-scheme">Configuring the versioning scheme</a>
</li>
<li class="main">
<a href="#api-reference">API Reference</a>
</li>
<li>
<a href="#python-3-support">Python 3 support</a>
<a href="#acceptheaderversioning">AcceptHeaderVersioning</a>
</li>
<li>
<a href="#deprecation-policy">Deprecation policy</a>
<a href="#urlparameterversioning">URLParameterVersioning</a>
</li>
<li>
<a href="#community">Community</a>
<a href="#namespaceversioning">NamespaceVersioning</a>
</li>
<li>
<a href="#api-changes">API changes</a>
<a href="#hostnameversioning">HostNameVersioning</a>
</li>
<li>
<a href="#queryparameterversioning">QueryParameterVersioning</a>
</li>
<li class="main">
<a href="#custom-versioning-schemes">Custom versioning schemes</a>
</li>
<li>
<a href="#example">Example</a>
</li>
......@@ -385,115 +409,157 @@
<div id="main-content" class="span9">
<a class="github" href="https://github.com/tomchristie/django-rest-framework/tree/master/rest_framework/versioning.py">
<span class="label label-info">versioning.py</span>
</a>
<h1 id="django-rest-framework-22">Django REST framework 2.2</h1>
<p>The 2.2 release represents an important point for REST framework, with the addition of Python 3 support, and the introduction of an official deprecation policy.</p>
<h2 id="python-3-support">Python 3 support</h2>
<p>Thanks to some fantastic work from <a href="https://github.com/xordoquy">Xavier Ordoquy</a>, Django REST framework 2.2 now supports Python 3. You'll need to be running Django 1.5, and it's worth keeping in mind that Django's Python 3 support is currently <a href="https://docs.djangoproject.com/en/dev/faq/install/#can-i-use-django-with-python-3">considered experimental</a>.</p>
<p>Django 1.6's Python 3 support is expected to be officially labeled as 'production-ready'.</p>
<p>If you want to start ensuring that your own projects are Python 3 ready, we can highly recommend Django's <a href="https://docs.djangoproject.com/en/dev/topics/python3/">Porting to Python 3</a> documentation.</p>
<p>Django REST framework's Python 2.6 support now requires 2.6.5 or above, in line with <a href="https://docs.djangoproject.com/en/dev/releases/1.5/#python-compatibility">Django 1.5's Python compatibility</a>.</p>
<h2 id="deprecation-policy">Deprecation policy</h2>
<p>We've now introduced an official deprecation policy, which is in line with <a href="https://docs.djangoproject.com/en/dev/internals/release-process/#internal-release-deprecation-policy">Django's deprecation policy</a>. This policy will make it easy for you to continue to track the latest, greatest version of REST framework.</p>
<p>The timeline for deprecation works as follows:</p>
<h1 id="versioning">Versioning</h1>
<blockquote>
<p>Versioning an interface is just a "polite" way to kill deployed clients.</p>
<p>&mdash; <a href="http://www.slideshare.net/evolve_conference/201308-fielding-evolve/31">Roy Fielding</a>.</p>
</blockquote>
<p>API versioning allows you to alter behavior between different clients. REST framework provides for a number of different versioning schemes.</p>
<p>Versioning is determined by the incoming client request, and may either be based on the request URL, or based on the request headers.</p>
<p>There are a number of valid approaches to approaching versioning. <a href="http://www.infoq.com/articles/roy-fielding-on-versioning">Non-versioned systems can also be appropriate</a>, particularly if you're engineering for very long-term systems with multiple clients outside of your control.</p>
<h2 id="versioning-with-rest-framework">Versioning with REST framework</h2>
<p>When API versioning is enabled, the <code>request.version</code> attribute will contain a string that corresponds to the version requested in the incoming client request.</p>
<p>By default, versioning is not enabled, and <code>request.version</code> will always return <code>None</code>.</p>
<h4 id="varying-behavior-based-on-the-version">Varying behavior based on the version</h4>
<p>How you vary the API behavior is up to you, but one example you might typically want is to switch to a different serialization style in a newer version. For example:</p>
<pre><code>def get_serializer_class(self):
if self.request.version == 'v1':
return AccountSerializerVersion1
return AccountSerializer
</code></pre>
<h4 id="reversing-urls-for-versioned-apis">Reversing URLs for versioned APIs</h4>
<p>The <code>reverse</code> function included by REST framework ties in with the versioning scheme. You need to make sure to include the current <code>request</code> as a keyword argument, like so.</p>
<pre><code>reverse('bookings-list', request=request)
</code></pre>
<p>The above function will apply any URL transformations appropriate to the request version. For example:</p>
<ul>
<li>If <code>NamespacedVersioning</code> was being used, and the API version was 'v1', then the URL lookup used would be <code>'v1:bookings-list'</code>, which might resolve to a URL like <code>http://example.org/v1/bookings/</code>.</li>
<li>If <code>QueryParameterVersioning</code> was being used, and the API version was <code>1.0</code>, then the returned URL might be something like <code>http://example.org/bookings/?version=1.0</code></li>
</ul>
<h4 id="versioned-apis-and-hyperlinked-serializers">Versioned APIs and hyperlinked serializers</h4>
<p>When using hyperlinked serialization styles together with a URL based versioning scheme make sure to include the request as context to the serializer.</p>
<pre><code>def get(self, request):
queryset = Booking.objects.all()
serializer = BookingsSerializer(queryset, many=True, context={'request': request})
return Response({'all_bookings': serializer.data})
</code></pre>
<p>Doing so will allow any returned URLs to include the appropriate versioning.</p>
<h2 id="configuring-the-versioning-scheme">Configuring the versioning scheme</h2>
<p>The versioning scheme is defined by the <code>DEFAULT_VERSIONING_CLASS</code> settings key.</p>
<pre><code>REST_FRAMEWORK = {
'DEFAULT_VERSIONING_CLASS': 'rest_framework.versioning.NamespaceVersioning'
}
</code></pre>
<p>Unless it is explicitly set, the value for <code>DEFAULT_VERSIONING_CLASS</code> will be <code>None</code>. In this case the <code>request.version</code> attribute will always return <code>None</code>.</p>
<p>You can also set the versioning scheme on an individual view. Typically you won't need to do this, as it makes more sense to have a single versioning scheme used globally. If you do need to do so, use the <code>versioning_class</code> attribute.</p>
<pre><code>class ProfileList(APIView):
versioning_class = versioning.QueryParameterVersioning
</code></pre>
<h4 id="other-versioning-settings">Other versioning settings</h4>
<p>The following settings keys are also used to control versioning:</p>
<ul>
<li>
<p>Version 2.2 introduces some API changes as detailed in the release notes. It remains fully backwards compatible with 2.1, but will raise <code>PendingDeprecationWarning</code> warnings if you use bits of API that are due to be deprecated. These warnings are silent by default, but can be explicitly enabled when you're ready to start migrating any required changes. For example if you start running your tests using <code>python -Wd manage.py test</code>, you'll be warned of any API changes you need to make.</p>
</li>
<li>
<p>Version 2.3 will escalate these warnings to <code>DeprecationWarning</code>, which is loud by default.</p>
</li>
<li>
<p>Version 2.4 will remove the deprecated bits of API entirely.</p>
</li>
<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. 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>
</ul>
<p>Note that in line with Django's policy, any parts of the framework not mentioned in the documentation should generally be considered private API, and may be subject to change.</p>
<h2 id="community">Community</h2>
<p>As of the 2.2 merge, we've also hit an impressive milestone. The number of committers listed in <a href="http://www.django-rest-framework.org/topics/credits">the credits</a>, is now at over <strong>one hundred individuals</strong>. Each name on that list represents at least one merged pull request, however large or small.</p>
<p>Our <a href="https://groups.google.com/forum/?fromgroups#!forum/django-rest-framework">mailing list</a> and #restframework IRC channel are also very active, and we've got a really impressive rate of development both on REST framework itself, and on third party packages such as the great <a href="https://github.com/marcgibbons/django-rest-framework-docs">django-rest-framework-docs</a> package from <a href="https://github.com/marcgibbons/">Marc Gibbons</a>.</p>
<hr />
<h2 id="api-changes">API changes</h2>
<p>The 2.2 release makes a few changes to the API, in order to make it more consistent, simple, and easier to use.</p>
<h3 id="cleaner-to-many-related-fields">Cleaner to-many related fields</h3>
<p>The <code>ManyRelatedField()</code> style is being deprecated in favor of a new <code>RelatedField(many=True)</code> syntax.</p>
<p>For example, if a user is associated with multiple questions, which we want to represent using a primary key relationship, we might use something like the following:</p>
<pre><code>class UserSerializer(serializers.HyperlinkedModelSerializer):
questions = serializers.PrimaryKeyRelatedField(many=True)
class Meta:
fields = ('username', 'questions')
<h1 id="api-reference">API Reference</h1>
<h2 id="acceptheaderversioning">AcceptHeaderVersioning</h2>
<p>This scheme requires the client to specify the version as part of the media type in the <code>Accept</code> header. The version is included as a media type parameter, that supplements the main media type.</p>
<p>Here's an example HTTP request using the accept header versioning style.</p>
<pre><code>GET /bookings/ HTTP/1.1
Host: example.com
Accept: application/json; version=1.0
</code></pre>
<p>The new syntax is cleaner and more obvious, and the change will also make the documentation cleaner, simplify the internal API, and make writing custom relational fields easier.</p>
<p>The change also applies to serializers. If you have a nested serializer, you should start using <code>many=True</code> for to-many relationships. For example, a serializer representation of an Album that can contain many Tracks might look something like this:</p>
<pre><code>class TrackSerializer(serializer.ModelSerializer):
class Meta:
model = Track
fields = ('name', 'duration')
class AlbumSerializer(serializer.ModelSerializer):
tracks = TrackSerializer(many=True)
class Meta:
model = Album
fields = ('album_name', 'artist', 'tracks')
<p>In the example request above <code>request.version</code> attribute would return the string <code>'1.0'</code>.</p>
<p>Versioning based on accept headers is <a href="http://blog.steveklabnik.com/posts/2011-07-03-nobody-understands-rest-or-http#i_want_my_api_to_be_versioned">generally considered</a> as <a href="https://github.com/interagent/http-api-design#version-with-accepts-header">best practice</a>, although other styles may be suitable depending on your client requirements.</p>
<h4 id="using-accept-headers-with-vendor-media-types">Using accept headers with vendor media types</h4>
<p>Strictly speaking the <code>json</code> media type is not specified as <a href="http://tools.ietf.org/html/rfc4627#section-6">including additional parameters</a>. If you are building a well-specified public API you might consider using a <a href="http://en.wikipedia.org/wiki/Internet_media_type#Vendor_tree">vendor media type</a>. To do so, configure your renderers to use a JSON based renderer with a custom media type:</p>
<pre><code>class BookingsAPIRenderer(JSONRenderer):
media_type = 'application/vnd.megacorp.bookings+json'
</code></pre>
<p>Additionally, the change also applies when serializing or deserializing data. For example to serialize a queryset of models you should now use the <code>many=True</code> flag.</p>
<pre><code>serializer = SnippetSerializer(Snippet.objects.all(), many=True)
serializer.data
<p>Your client requests would now look like this:</p>
<pre><code>GET /bookings/ HTTP/1.1
Host: example.com
Accept: application/vnd.megacorp.bookings+json; version=1.0
</code></pre>
<p>This more explicit behavior on serializing and deserializing data <a href="https://github.com/tomchristie/django-rest-framework/issues/564">makes integration with non-ORM backends such as MongoDB easier</a>, as instances to be serialized can include the <code>__iter__</code> method, without incorrectly triggering list-based serialization, or requiring workarounds.</p>
<p>The implicit to-many behavior on serializers, and the <code>ManyRelatedField</code> style classes will continue to function, but will raise a <code>PendingDeprecationWarning</code>, which can be made visible using the <code>-Wd</code> flag.</p>
<p><strong>Note</strong>: If you need to forcibly turn off the implicit "<code>many=True</code> for <code>__iter__</code> objects" behavior, you can now do so by specifying <code>many=False</code>. This will become the default (instead of the current default of <code>None</code>) once the deprecation of the implicit behavior is finalised in version 2.4.</p>
<h3 id="cleaner-optional-relationships">Cleaner optional relationships</h3>
<p>Serializer relationships for nullable Foreign Keys will change from using the current <code>null=True</code> flag, to instead using <code>required=False</code>.</p>
<p>For example, is a user account has an optional foreign key to a company, that you want to express using a hyperlink, you might use the following field in a <code>Serializer</code> class:</p>
<pre><code>current_company = serializers.HyperlinkedRelatedField(required=False)
<h2 id="urlparameterversioning">URLParameterVersioning</h2>
<p>This scheme requires the client to specify the version as part of the URL path.</p>
<pre><code>GET /v1/bookings/ HTTP/1.1
Host: example.com
Accept: application/json
</code></pre>
<p>This is in line both with the rest of the serializer fields API, and with Django's <code>Form</code> and <code>ModelForm</code> API.</p>
<p>Using <code>required</code> throughout the serializers API means you won't need to consider if a particular field should take <code>blank</code> or <code>null</code> arguments instead of <code>required</code>, and also means there will be more consistent behavior for how fields are treated when they are not present in the incoming data.</p>
<p>The <code>null=True</code> argument will continue to function, and will imply <code>required=False</code>, but will raise a <code>PendingDeprecationWarning</code>.</p>
<h3 id="cleaner-charfield-syntax">Cleaner CharField syntax</h3>
<p>The <code>CharField</code> API previously took an optional <code>blank=True</code> argument, which was intended to differentiate between null CharField input, and blank CharField input.</p>
<p>In keeping with Django's CharField API, REST framework's <code>CharField</code> will only ever return the empty string, for missing or <code>None</code> inputs. The <code>blank</code> flag will no longer be in use, and you should instead just use the <code>required=&lt;bool&gt;</code> flag. For example:</p>
<pre><code>extra_details = CharField(required=False)
<p>Your URL conf must include a pattern that matches the version with a <code>'version'</code> keyword argument, so that this information is available to the versioning scheme.</p>
<pre><code>urlpatterns = [
url(
r'^(?P&lt;version&gt;{v1,v2})/bookings/$',
bookings_list,
name='bookings-list'
),
url(
r'^(?P&lt;version&gt;{v1,v2})/bookings/(?P&lt;pk&gt;[0-9]+)/$',
bookings_detail,
name='bookings-detail'
)
]
</code></pre>
<p>The <code>blank</code> keyword argument will continue to function, but will raise a <code>PendingDeprecationWarning</code>.</p>
<h3 id="simpler-object-level-permissions">Simpler object-level permissions</h3>
<p>Custom permissions classes previously used the signature <code>.has_permission(self, request, view, obj=None)</code>. This method would be called twice, firstly for the global permissions check, with the <code>obj</code> parameter set to <code>None</code>, and again for the object-level permissions check when appropriate, with the <code>obj</code> parameter set to the relevant model instance.</p>
<p>The global permissions check and object-level permissions check are now separated into two separate methods, which gives a cleaner, more obvious API.</p>
<ul>
<li>Global permission checks now use the <code>.has_permission(self, request, view)</code> signature.</li>
<li>Object-level permission checks use a new method <code>.has_object_permission(self, request, view, obj)</code>.</li>
</ul>
<p>For example, the following custom permission class:</p>
<pre><code>class IsOwner(permissions.BasePermission):
"""
Custom permission to only allow owners of an object to view or edit it.
Model instances are expected to include an `owner` attribute.
"""
def has_permission(self, request, view, obj=None):
if obj is None:
# Ignore global permissions check
return True
return obj.owner == request.user
<h2 id="namespaceversioning">NamespaceVersioning</h2>
<p>To the client, this scheme is the same as <code>URLParameterVersioning</code>. The only difference is how it is configured in your Django application, as it uses URL namespacing, instead of URL keyword arguments.</p>
<pre><code>GET /v1/something/ HTTP/1.1
Host: example.com
Accept: application/json
</code></pre>
<p>With this scheme the <code>request.version</code> attribute is determined based on the <code>namespace</code> that matches the incoming request path.</p>
<p>In the following example we're giving a set of views two different possible URL prefixes, each under a different namespace:</p>
<pre><code># bookings/urls.py
urlpatterns = [
url(r'^$', bookings_list, name='bookings-list'),
url(r'^(?P&lt;pk&gt;[0-9]+)/$', bookings_detail, name='bookings-detail')
]
# urls.py
urlpatterns = [
url(r'^v1/bookings/', include('bookings.urls', namespace='v1')),
url(r'^v2/bookings/', include('bookings.urls', namespace='v2'))
]
</code></pre>
<p>Both <code>URLParameterVersioning</code> and <code>NamespaceVersioning</code> are reasonable if you just need a simple versioning scheme. The <code>URLParameterVersioning</code> approach might be better suitable for small ad-hoc projects, and the <code>NamespaceVersioning</code> is probably easier to manage for larger projects.</p>
<h2 id="hostnameversioning">HostNameVersioning</h2>
<p>The hostname versioning scheme requires the client to specify the requested version as part of the hostname in the URL.</p>
<p>For example the following is an HTTP request to the <code>http://v1.example.com/bookings/</code> URL:</p>
<pre><code>GET /bookings/ HTTP/1.1
Host: v1.example.com
Accept: application/json
</code></pre>
<p>Now becomes:</p>
<pre><code>class IsOwner(permissions.BasePermission):
"""
Custom permission to only allow owners of an object to view or edit it.
Model instances are expected to include an `owner` attribute.
"""
def has_object_permission(self, request, view, obj):
return obj.owner == request.user
<p>By default this implementation expects the hostname to match this simple regular expression:</p>
<pre><code>^([a-zA-Z0-9]+)\.[a-zA-Z0-9]+\.[a-zA-Z0-9]+$
</code></pre>
<p>Note that the first group is enclosed in brackets, indicating that this is the matched portion of the hostname.</p>
<p>The <code>HostNameVersioning</code> scheme can be awkward to use in debug mode as you will typically be accessing a raw IP address such as <code>127.0.0.1</code>. There are various online services which you to <a href="https://reinteractive.net/posts/199-developing-and-testing-rails-applications-with-subdomains">access localhost with a custom subdomain</a> which you may find helpful in this case.</p>
<p>Hostname based versioning can be particularly useful if you have requirements to route incoming requests to different servers based on the version, as you can configure different DNS records for different API versions.</p>
<h2 id="queryparameterversioning">QueryParameterVersioning</h2>
<p>This scheme is a simple style that includes the version as a query parameter in the URL. For example:</p>
<pre><code>GET /something/?version=0.1 HTTP/1.1
Host: example.com
Accept: application/json
</code></pre>
<hr />
<h1 id="custom-versioning-schemes">Custom versioning schemes</h1>
<p>To implement a custom versioning scheme, subclass <code>BaseVersioning</code> and override the <code>.determine_version</code> method.</p>
<h2 id="example">Example</h2>
<p>The following example uses a custom <code>X-API-Version</code> header to determine the requested version.</p>
<pre><code>class XAPIVersionScheme(versioning.BaseVersioning):
def determine_version(self, request, *args, **kwargs):
return request.META.get('HTTP_X_API_VERSION', None)
</code></pre>
<p>If you're overriding the <code>BasePermission</code> class, the old-style signature will continue to function, and will correctly handle both global and object-level permissions checks, but its use will raise a <code>PendingDeprecationWarning</code>.</p>
<p>Note also that the usage of the internal APIs for permission checking on the <code>View</code> class has been cleaned up slightly, and is now documented and subject to the deprecation policy in all future versions.</p>
<h3 id="more-explicit-hyperlink-relations-behavior">More explicit hyperlink relations behavior</h3>
<p>When using a serializer with a <code>HyperlinkedRelatedField</code> or <code>HyperlinkedIdentityField</code>, the hyperlinks would previously use absolute URLs if the serializer context included a <code>'request'</code> key, and fall back to using relative URLs otherwise. This could lead to non-obvious behavior, as it might not be clear why some serializers generated absolute URLs, and others do not.</p>
<p>From version 2.2 onwards, serializers with hyperlinked relationships <em>always</em> require a <code>'request'</code> key to be supplied in the context dictionary. The implicit behavior will continue to function, but its use will raise a <code>PendingDeprecationWarning</code>.</p>
<p>If your versioning scheme is based on the request URL, you will also want to alter how versioned URLs are determined. In order to do so you should override the <code>.reverse()</code> method on the class. See the source code for examples.</p>
</div>
<!--/span-->
......
api-guide/views/index.html
......@@ -189,6 +189,10 @@
</li>
<li >
<a href="../versioning">Versioning</a>
</li>
<li >
<a href="../content-negotiation">Content negotiation</a>
</li>
......@@ -232,6 +236,10 @@
</li>
<li >
<a href="../../topics/internationalization">Internationalization</a>
</li>
<li >
<a href="../../topics/ajax-csrf-cors">AJAX, CSRF & CORS</a>
</li>
......@@ -260,23 +268,11 @@
</li>
<li >
<a href="../../topics/rest-framework-2-announcement">2.0 Announcement</a>
</li>
<li >
<a href="../../topics/2.2-announcement">2.2 Announcement</a>
</li>
<li >
<a href="../../topics/2.3-announcement">2.3 Announcement</a>
</li>
<li >
<a href="../../topics/2.4-announcement">2.4 Announcement</a>
<a href="../../topics/3.0-announcement">3.0 Announcement</a>
</li>
<li >
<a href="../../topics/3.0-announcement">3.0 Announcement</a>
<a href="../../topics/3.1-announcement">3.1 Announcement</a>
</li>
<li >
......@@ -287,10 +283,6 @@
<a href="../../topics/release-notes">Release Notes</a>
</li>
<li >
<a href="../../topics/credits">Credits</a>
</li>
</ul>
</li>
......
api-guide/viewsets/index.html
......@@ -189,6 +189,10 @@
</li>
<li >
<a href="../versioning">Versioning</a>
</li>
<li >
<a href="../content-negotiation">Content negotiation</a>
</li>
......@@ -232,6 +236,10 @@
</li>
<li >
<a href="../../topics/internationalization">Internationalization</a>
</li>
<li >
<a href="../../topics/ajax-csrf-cors">AJAX, CSRF & CORS</a>
</li>
......@@ -260,23 +268,11 @@
</li>
<li >
<a href="../../topics/rest-framework-2-announcement">2.0 Announcement</a>
</li>
<li >
<a href="../../topics/2.2-announcement">2.2 Announcement</a>
</li>
<li >
<a href="../../topics/2.3-announcement">2.3 Announcement</a>
</li>
<li >
<a href="../../topics/2.4-announcement">2.4 Announcement</a>
<a href="../../topics/3.0-announcement">3.0 Announcement</a>
</li>
<li >
<a href="../../topics/3.0-announcement">3.0 Announcement</a>
<a href="../../topics/3.1-announcement">3.1 Announcement</a>
</li>
<li >
......@@ -287,10 +283,6 @@
<a href="../../topics/release-notes">Release Notes</a>
</li>
<li >
<a href="../../topics/credits">Credits</a>
</li>
</ul>
</li>
......@@ -566,7 +558,7 @@ class UserViewSet(viewsets.ModelViewSet):
<p>The <code>ModelViewSet</code> class inherits from <code>GenericAPIView</code> and includes implementations for various actions, by mixing in the behavior of the various mixin classes.</p>
<p>The actions provided by the <code>ModelViewSet</code> class are <code>.list()</code>, <code>.retrieve()</code>, <code>.create()</code>, <code>.update()</code>, and <code>.destroy()</code>.</p>
<h4 id="example_1">Example</h4>
<p>Because <code>ModelViewSet</code> extends <code>GenericAPIView</code>, you'll normally need to provide at least the <code>queryset</code> and <code>serializer_class</code> attributes, or the <code>model</code> attribute shortcut. For example:</p>
<p>Because <code>ModelViewSet</code> extends <code>GenericAPIView</code>, you'll normally need to provide at least the <code>queryset</code> and <code>serializer_class</code> attributes. For example:</p>
<pre><code>class AccountViewSet(viewsets.ModelViewSet):
"""
A simple ViewSet for viewing and editing accounts.
......
css/default.css
......@@ -171,6 +171,25 @@ body{
background-attachment: fixed;
}
#main-content h1:first-of-type {
margin-top: 0
}
#main-content h1, #main-content h2 {
font-weight: 300;
margin-top: 20px
}
#main-content h3, #main-content h4, #main-content h5 {
font-weight: 500;
margin-top: 15px
}
#main-content img {
display: block;
margin: 40px auto;
}
/* custom navigation styles */
.navbar .navbar-inner{
......@@ -239,6 +258,10 @@ body a:hover{
}
}
h1 code, h2 code, h3 code, h4 code, h5 code {
color: #333;
}
/* sticky footer and footer */
html, body {
height: 100%;
......
img/.DS_Store 0 → 100644
File added
index.html
......@@ -189,6 +189,10 @@
</li>
<li >
<a href="api-guide/versioning/">Versioning</a>
</li>
<li >
<a href="api-guide/content-negotiation/">Content negotiation</a>
</li>
......@@ -232,6 +236,10 @@
</li>
<li >
<a href="topics/internationalization/">Internationalization</a>
</li>
<li >
<a href="topics/ajax-csrf-cors/">AJAX, CSRF & CORS</a>
</li>
......@@ -260,23 +268,11 @@
</li>
<li >
<a href="topics/rest-framework-2-announcement/">2.0 Announcement</a>
</li>
<li >
<a href="topics/2.2-announcement/">2.2 Announcement</a>
</li>
<li >
<a href="topics/2.3-announcement/">2.3 Announcement</a>
</li>
<li >
<a href="topics/2.4-announcement/">2.4 Announcement</a>
<a href="topics/3.0-announcement/">3.0 Announcement</a>
</li>
<li >
<a href="topics/3.0-announcement/">3.0 Announcement</a>
<a href="topics/3.1-announcement/">3.1 Announcement</a>
</li>
<li >
......@@ -287,10 +283,6 @@
<a href="topics/release-notes/">Release Notes</a>
</li>
<li >
<a href="topics/credits/">Credits</a>
</li>
</ul>
</li>
......@@ -489,7 +481,7 @@
<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>
<li><a href="api-guide/authentication/">Authentication policies</a> including <a href="./api-guide/authentication#oauthauthentication">OAuth1a</a> and <a href="./api-guide/authentication#oauth2authentication">OAuth2</a> out of the box.</li>
<li><a href="api-guide/authentication/">Authentication policies</a> including packages for <a href="./api-guide/authentication/#django-rest-framework-oauth">OAuth1a</a> and <a href="./api-guide/authentication/#django-oauth-toolkit">OAuth2</a>.</li>
<li><a href="api-guide/serializers/">Serialization</a> that supports both <a href="./api-guide/serializers#modelserializer">ORM</a> and <a href="./api-guide/serializers#serializers">non-ORM</a> data sources.</li>
<li>Customizable all the way down - just use <a href="./api-guide/views#function-based-views">regular function-based views</a> if you don't need the <a href="api-guide/generic-views/">more</a> <a href="api-guide/viewsets/">powerful</a> <a href="api-guide/routers/">features</a>.</li>
<li><a href="./.">Extensive documentation</a>, and <a href="https://groups.google.com/forum/?fromgroups#!forum/django-rest-framework">great community support</a>.</li>
......@@ -502,19 +494,14 @@
<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.4.11+, 1.5.6+, 1.6.3+, 1.7)</li>
<li>Django (1.4.11+, 1.5.6+, 1.6.3+, 1.7, 1.8-beta)</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/PyYAML">PyYAML</a> (3.10+) - YAML content-type support.</li>
<li><a href="https://pypi.python.org/pypi/defusedxml">defusedxml</a> (0.3+) - XML content-type support.</li>
<li><a href="http://pypi.python.org/pypi/django-filter">django-filter</a> (0.9.2+) - Filtering support.</li>
<li><a href="https://bitbucket.org/david/django-oauth-plus/wiki/Home">django-oauth-plus</a> (2.0+) and <a href="https://github.com/simplegeo/python-oauth2">oauth2</a> (1.5.211+) - OAuth 1.0a support.</li>
<li><a href="https://github.com/caffeinehit/django-oauth2-provider">django-oauth2-provider</a> (0.2.3+) - OAuth 2.0 support.</li>
<li><a href="https://github.com/lukaszb/django-guardian">django-guardian</a> (1.1.1+) - Object level permissions support.</li>
</ul>
<p><strong>Note</strong>: The <code>oauth2</code> Python package is badly misnamed, and actually provides OAuth 1.0a support. Also note that packages required for both OAuth 1.0a, and OAuth 2.0 are not yet Python 3 compatible.</p>
<h2 id="installation">Installation</h2>
<p>Install using <code>pip</code>, including any optional packages you want...</p>
<pre><code>pip install djangorestframework
......@@ -612,6 +599,7 @@ urlpatterns = [
<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>
......@@ -632,14 +620,10 @@ urlpatterns = [
<li><a href="topics/third-party-resources/">Third Party Resources</a></li>
<li><a href="topics/contributing/">Contributing to REST framework</a></li>
<li><a href="topics/project-management/">Project management</a></li>
<li><a href="topics/rest-framework-2-announcement/">2.0 Announcement</a></li>
<li><a href="topics/2.2-announcement/">2.2 Announcement</a></li>
<li><a href="topics/2.3-announcement/">2.3 Announcement</a></li>
<li><a href="topics/2.4-announcement/">2.4 Announcement</a></li>
<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/kickstarter-announcement/">Kickstarter Announcement</a></li>
<li><a href="topics/release-notes/">Release Notes</a></li>
<li><a href="topics/credits/">Credits</a></li>
</ul>
<h2 id="development">Development</h2>
<p>See the <a href="topics/contributing/">Contribution guidelines</a> for information on how to clone
......
topics/2.3-announcement/index.html deleted 100644 → 0
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta charset="utf-8">
<title>2.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/2.3-announcement/" />
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="description" content="Django, API, REST, 2.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="../2.4-announcement">
Next <i class="icon-arrow-right icon-white"></i>
</a>
<a class="repo-link btn btn-inverse btn-small " rel="next" href="../2.2-announcement">
<i class="icon-arrow-left icon-white"></i> Previous
</a>
<a class="repo-link btn btn-inverse btn-small" href="#searchModal" data-toggle="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/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="../ajax-csrf-cors">AJAX, CSRF & CORS</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="../rest-framework-2-announcement">2.0 Announcement</a>
</li>
<li >
<a href="../2.2-announcement">2.2 Announcement</a>
</li>
<li class="active" >
<a href=".">2.3 Announcement</a>
</li>
<li >
<a href="../2.4-announcement">2.4 Announcement</a>
</li>
<li >
<a href="../3.0-announcement">3.0 Announcement</a>
</li>
<li >
<a href="../kickstarter-announcement">Kickstarter Announcement</a>
</li>
<li >
<a href="../release-notes">Release Notes</a>
</li>
<li >
<a href="../credits">Credits</a>
</li>
</ul>
</li>
</ul>
</div>
<!--/.nav-collapse -->
</div>
</div>
</div>
<div class="body-content">
<div class="container-fluid">
<!-- Search Modal -->
<div id="searchModal" 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">
<!-- Custom google search -->
<script>
(function() {
var cx = '015016005043623903336:rxraeohqk6w';
var gcse = document.createElement('script');
gcse.type = 'text/javascript';
gcse.async = true;
gcse.src = (document.location.protocol == 'https:' ? 'https:' : 'http:') +
'//www.google.com/cse/cse.js?cx=' + cx;
var s = document.getElementsByTagName('script')[0];
s.parentNode.insertBefore(gcse, s);
})();
</script>
<gcse:search></gcse:search>
</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">
<!-- TODO
<p style="margin-top: -12px">
<a class="btn btn-mini btn-primary" style="width: 60px">&laquo; previous</a>
<a class="btn btn-mini btn-primary" style="float: right; margin-right: 8px; width: 60px;">next &raquo;</a>
</p>
-->
<div id="table-of-contents">
<ul class="nav nav-list side-nav well sidebar-nav-fixed">
<li class="main">
<a href="#django-rest-framework-23">Django REST framework 2.3</a>
</li>
<li>
<a href="#viewsets-and-routers">ViewSets and Routers</a>
</li>
<li>
<a href="#simpler-views">Simpler views</a>
</li>
<li>
<a href="#easier-serializers">Easier Serializers</a>
</li>
<li>
<a href="#more-flexible-filtering">More flexible filtering</a>
</li>
<li class="main">
<a href="#api-changes">API Changes</a>
</li>
<li>
<a href="#simplified-generic-view-classes">Simplified generic view classes</a>
</li>
<li>
<a href="#simpler-url-lookups">Simpler URL lookups</a>
</li>
<li>
<a href="#fileuploadparser">FileUploadParser</a>
</li>
<li>
<a href="#decimalfield">DecimalField</a>
</li>
<li>
<a href="#modelserializers-and-reverse-relationships">ModelSerializers and reverse relationships</a>
</li>
<li>
<a href="#view-names-and-descriptions">View names and descriptions</a>
</li>
<li class="main">
<a href="#other-notes">Other notes</a>
</li>
<li>
<a href="#more-explicit-style">More explicit style</a>
</li>
<li>
<a href="#django-13-support">Django 1.3 support</a>
</li>
<li>
<a href="#version-22-api-changes">Version 2.2 API changes</a>
</li>
<li>
<a href="#what-comes-next">What comes next?</a>
</li>
</ul>
</div>
</div>
<div id="main-content" class="span9">
<h1 id="django-rest-framework-23">Django REST framework 2.3</h1>
<p>REST framework 2.3 makes it even quicker and easier to build your Web APIs.</p>
<h2 id="viewsets-and-routers">ViewSets and Routers</h2>
<p>The 2.3 release introduces the <a href="../../api-guide/viewsets">ViewSet</a> and <a href="../../api-guide/routers">Router</a> classes.</p>
<p>A viewset is simply a type of class based view that allows you to group multiple views into a single common class.</p>
<p>Routers allow you to automatically determine the URLconf for your viewset classes.</p>
<p>As an example of just how simple REST framework APIs can now be, here's an API written in a single <code>urls.py</code> module:</p>
<pre><code>"""
A REST framework API for viewing and editing users and groups.
"""
from django.conf.urls.defaults import url, include
from django.contrib.auth.models import User, Group
from rest_framework import viewsets, routers
# ViewSets define the view behavior.
class UserViewSet(viewsets.ModelViewSet):
model = User
class GroupViewSet(viewsets.ModelViewSet):
model = Group
# Routers provide an easy way of automatically determining the URL conf
router = routers.DefaultRouter()
router.register(r'users', UserViewSet)
router.register(r'groups', GroupViewSet)
# Wire up our API using automatic URL routing.
# Additionally, we include login URLs for the browsable API.
urlpatterns = [
url(r'^', include(router.urls)),
url(r'^api-auth/', include('rest_framework.urls', namespace='rest_framework'))
]
</code></pre>
<p>The best place to get started with ViewSets and Routers is to take a look at the <a href="../../tutorial/6-viewsets-and-routers">newest section in the tutorial</a>, which demonstrates their usage.</p>
<h2 id="simpler-views">Simpler views</h2>
<p>This release rationalises the API and implementation of the generic views, dropping the dependency on Django's <code>SingleObjectMixin</code> and <code>MultipleObjectMixin</code> classes, removing a number of unneeded attributes, and generally making the implementation more obvious and easy to work with.</p>
<p>This improvement is reflected in improved documentation for the <code>GenericAPIView</code> base class, and should make it easier to determine how to override methods on the base class if you need to write customized subclasses.</p>
<h2 id="easier-serializers">Easier Serializers</h2>
<p>REST framework lets you be totally explicit regarding how you want to represent relationships, allowing you to choose between styles such as hyperlinking or primary key relationships.</p>
<p>The ability to specify exactly how you want to represent relationships is powerful, but it also introduces complexity. In order to keep things more simple, REST framework now allows you to include reverse relationships simply by including the field name in the <code>fields</code> metadata of the serializer class.</p>
<p>For example, in REST framework 2.2, reverse relationships needed to be included explicitly on a serializer class.</p>
<pre><code>class BlogSerializer(serializers.ModelSerializer):
comments = serializers.PrimaryKeyRelatedField(many=True)
class Meta:
model = Blog
fields = ('id', 'title', 'created', 'comments')
</code></pre>
<p>As of 2.3, you can simply include the field name, and the appropriate serializer field will automatically be used for the relationship.</p>
<pre><code>class BlogSerializer(serializers.ModelSerializer):
"""
Don't need to specify the 'comments' field explicitly anymore.
"""
class Meta:
model = Blog
fields = ('id', 'title', 'created', 'comments')
</code></pre>
<p>Similarly, you can now easily include the primary key in hyperlinked relationships, simply by adding the field name to the metadata.</p>
<pre><code>class BlogSerializer(serializers.HyperlinkedModelSerializer):
"""
This is a hyperlinked serializer, which default to using
a field named 'url' as the primary identifier.
Note that we can now easily also add in the 'id' field.
"""
class Meta:
model = Blog
fields = ('url', 'id', 'title', 'created', 'comments')
</code></pre>
<h2 id="more-flexible-filtering">More flexible filtering</h2>
<p>The <code>FILTER_BACKEND</code> setting has moved to pending deprecation, in favor of a <code>DEFAULT_FILTER_BACKENDS</code> setting that takes a <em>list</em> of filter backend classes, instead of a single filter backend class.</p>
<p>The generic view <code>filter_backend</code> attribute has also been moved to pending deprecation in favor of a <code>filter_backends</code> setting.</p>
<p>Being able to specify multiple filters will allow for more flexible, powerful behavior. New filter classes to handle searching and ordering of results are planned to be released shortly.</p>
<hr />
<h1 id="api-changes">API Changes</h1>
<h2 id="simplified-generic-view-classes">Simplified generic view classes</h2>
<p>The functionality provided by <code>SingleObjectAPIView</code> and <code>MultipleObjectAPIView</code> base classes has now been moved into the base class <code>GenericAPIView</code>. The implementation of this base class is simple enough that providing subclasses for the base classes of detail and list views is somewhat unnecessary.</p>
<p>Additionally the base generic view no longer inherits from Django's <code>SingleObjectMixin</code> or <code>MultipleObjectMixin</code> classes, simplifying the implementation, and meaning you don't need to cross-reference across to Django's codebase.</p>
<p>Using the <code>SingleObjectAPIView</code> and <code>MultipleObjectAPIView</code> base classes continues to be supported, but will raise a <code>PendingDeprecationWarning</code>. You should instead simply use <code>GenericAPIView</code> as the base for any generic view subclasses.</p>
<h3 id="removed-attributes">Removed attributes</h3>
<p>The following attributes and methods, were previously present as part of Django's generic view implementations, but were unneeded and unused and have now been entirely removed.</p>
<ul>
<li>context_object_name</li>
<li>get_context_data()</li>
<li>get_context_object_name()</li>
</ul>
<p>The following attributes and methods, which were previously present as part of Django's generic view implementations have also been entirely removed.</p>
<ul>
<li>paginator_class</li>
<li>get_paginator()</li>
<li>get_allow_empty()</li>
<li>get_slug_field()</li>
</ul>
<p>There may be cases when removing these bits of API might mean you need to write a little more code if your view has highly customized behavior, but generally we believe that providing a coarser-grained API will make the views easier to work with, and is the right trade-off to make for the vast majority of cases.</p>
<p>Note that the listed attributes and methods have never been a documented part of the REST framework API, and as such are not covered by the deprecation policy.</p>
<h3 id="simplified-methods">Simplified methods</h3>
<p>The <code>get_object</code> and <code>get_paginate_by</code> methods no longer take an optional queryset argument. This makes overridden these methods more obvious, and a little more simple.</p>
<p>Using an optional queryset with these methods continues to be supported, but will raise a <code>PendingDeprecationWarning</code>.</p>
<p>The <code>paginate_queryset</code> method no longer takes a <code>page_size</code> argument, or returns a four-tuple of pagination information. Instead it simply takes a queryset argument, and either returns a <code>page</code> object with an appropriate page size, or returns <code>None</code>, if pagination is not configured for the view.</p>
<p>Using the <code>page_size</code> argument is still supported and will trigger the old-style return type, but will raise a <code>PendingDeprecationWarning</code>.</p>
<h3 id="deprecated-attributes">Deprecated attributes</h3>
<p>The following attributes are used to control queryset lookup, and have all been moved into a pending deprecation state.</p>
<ul>
<li>pk_url_kwarg = 'pk'</li>
<li>slug_url_kwarg = 'slug'</li>
<li>slug_field = 'slug'</li>
</ul>
<p>Their usage is replaced with a single attribute:</p>
<ul>
<li>lookup_field = 'pk'</li>
</ul>
<p>This attribute is used both as the regex keyword argument in the URL conf, and as the model field to filter against when looking up a model instance. To use non-pk based lookup, simply set the <code>lookup_field</code> argument to an alternative field, and ensure that the keyword argument in the url conf matches the field name.</p>
<p>For example, a view with 'username' based lookup might look like this:</p>
<pre><code>class UserDetail(generics.RetrieveAPIView):
lookup_field = 'username'
queryset = User.objects.all()
serializer_class = UserSerializer
</code></pre>
<p>And would have the following entry in the urlconf:</p>
<pre><code> url(r'^users/(?P&lt;username&gt;\w+)/$', UserDetail.as_view()),
</code></pre>
<p>Usage of the old-style attributes continues to be supported, but will raise a <code>PendingDeprecationWarning</code>.</p>
<p>The <code>allow_empty</code> attribute is also deprecated. To use <code>allow_empty=False</code> style behavior you should explicitly override <code>get_queryset</code> and raise an <code>Http404</code> on empty querysets.</p>
<p>For example:</p>
<pre><code>class DisallowEmptyQuerysetMixin(object):
def get_queryset(self):
queryset = super(DisallowEmptyQuerysetMixin, self).get_queryset()
if not queryset.exists():
raise Http404
return queryset
</code></pre>
<p>In our opinion removing lesser-used attributes like <code>allow_empty</code> helps us move towards simpler generic view implementations, making them more obvious to use and override, and re-enforcing the preferred style of developers writing their own base classes and mixins for custom behavior rather than relying on the configurability of the generic views.</p>
<h2 id="simpler-url-lookups">Simpler URL lookups</h2>
<p>The <code>HyperlinkedRelatedField</code> class now takes a single optional <code>lookup_field</code> argument, that replaces the <code>pk_url_kwarg</code>, <code>slug_url_kwarg</code>, and <code>slug_field</code> arguments.</p>
<p>For example, you might have a field that references it's relationship by a hyperlink based on a slug field:</p>
<pre><code> account = HyperlinkedRelatedField(read_only=True,
lookup_field='slug',
view_name='account-detail')
</code></pre>
<p>Usage of the old-style attributes continues to be supported, but will raise a <code>PendingDeprecationWarning</code>.</p>
<h2 id="fileuploadparser">FileUploadParser</h2>
<p>2.3 adds a <code>FileUploadParser</code> parser class, that supports raw file uploads, in addition to the existing multipart upload support.</p>
<h2 id="decimalfield">DecimalField</h2>
<p>2.3 introduces a <code>DecimalField</code> serializer field, which returns <code>Decimal</code> instances.</p>
<p>For most cases APIs using model fields will behave as previously, however if you are using a custom renderer, not provided by REST framework, then you may now need to add support for rendering <code>Decimal</code> instances to your renderer implementation.</p>
<h2 id="modelserializers-and-reverse-relationships">ModelSerializers and reverse relationships</h2>
<p>The support for adding reverse relationships to the <code>fields</code> option on a <code>ModelSerializer</code> class means that the <code>get_related_field</code> and <code>get_nested_field</code> method signatures have now changed.</p>
<p>In the unlikely event that you're providing a custom serializer class, and implementing these methods you should note the new call signature for both methods is now <code>(self, model_field, related_model, to_many)</code>. For reverse relationships <code>model_field</code> will be <code>None</code>.</p>
<p>The old-style signature will continue to function but will raise a <code>PendingDeprecationWarning</code>.</p>
<h2 id="view-names-and-descriptions">View names and descriptions</h2>
<p>The mechanics of how the names and descriptions used in the browsable API are generated has been modified and cleaned up somewhat.</p>
<p>If you've been customizing this behavior, for example perhaps to use <code>rst</code> markup for the browsable API, then you'll need to take a look at the implementation to see what updates you need to make.</p>
<p>Note that the relevant methods have always been private APIs, and the docstrings called them out as intended to be deprecated.</p>
<hr />
<h1 id="other-notes">Other notes</h1>
<h2 id="more-explicit-style">More explicit style</h2>
<p>The usage of <code>model</code> attribute in generic Views is still supported, but it's usage is generally being discouraged throughout the documentation, in favour of the setting the more explicit <code>queryset</code> and <code>serializer_class</code> attributes.</p>
<p>For example, the following is now the recommended style for using generic views:</p>
<pre><code>class AccountListView(generics.RetrieveAPIView):
queryset = MyModel.objects.all()
serializer_class = MyModelSerializer
</code></pre>
<p>Using an explicit <code>queryset</code> and <code>serializer_class</code> attributes makes the functioning of the view more clear than using the shortcut <code>model</code> attribute.</p>
<p>It also makes the usage of the <code>get_queryset()</code> or <code>get_serializer_class()</code> methods more obvious.</p>
<pre><code>class AccountListView(generics.RetrieveAPIView):
serializer_class = MyModelSerializer
def get_queryset(self):
"""
Determine the queryset dynamically, depending on the
user making the request.
Note that overriding this method follows on more obviously now
that an explicit `queryset` attribute is the usual view style.
"""
return self.user.accounts
</code></pre>
<h2 id="django-13-support">Django 1.3 support</h2>
<p>The 2.3.x release series will be the last series to provide compatibility with Django 1.3.</p>
<h2 id="version-22-api-changes">Version 2.2 API changes</h2>
<p>All API changes in 2.2 that previously raised <code>PendingDeprecationWarning</code> will now raise a <code>DeprecationWarning</code>, which is loud by default.</p>
<h2 id="what-comes-next">What comes next?</h2>
<ul>
<li>Support for read-write nested serializers is almost complete, and due to be released in the next few weeks.</li>
<li>Extra filter backends for searching and ordering of results are planned to be added shortly.</li>
</ul>
<p>The next few months should see a renewed focus on addressing outstanding tickets. The 2.4 release is currently planned for around August-September.</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>.</a>
</p>
</footer>
<!-- Le javascript
================================================== -->
<!-- Placed at the end of the document so the pages load faster -->
<script src="../../js/jquery-1.8.1-min.js"></script>
<script src="../../js/prettify-1.0.js"></script>
<script src="../../js/bootstrap-2.1.1-min.js"></script>
<script src="../../js/theme.js"></script>
<script>
//$('.side-nav').scrollspy()
var shiftWindow = function() {
scrollBy(0, -50)
};
if (location.hash) shiftWindow();
window.addEventListener("hashchange", shiftWindow);
$('.dropdown-menu').on('click touchstart', function(event) {
event.stopPropagation();
});
// Dynamically force sidenav to no higher than browser window
$('.side-nav').css('max-height', window.innerHeight - 130);
$(function() {
$(window).resize(function() {
$('.side-nav').css('max-height', window.innerHeight - 130);
});
});
</script>
</body>
</html>
\ No newline at end of file
topics/3.0-announcement/index.html
......@@ -62,10 +62,10 @@
<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.1-announcement">
Next <i class="icon-arrow-right icon-white"></i>
</a>
<a class="repo-link btn btn-inverse btn-small " rel="next" href="../2.4-announcement">
<a class="repo-link btn btn-inverse btn-small " rel="next" href="../project-management">
<i class="icon-arrow-left icon-white"></i> Previous
</a>
<a class="repo-link btn btn-inverse btn-small" href="#searchModal" data-toggle="modal"><i class="icon-search icon-white"></i> Search</a>
......@@ -189,6 +189,10 @@
</li>
<li >
<a href="../../api-guide/versioning">Versioning</a>
</li>
<li >
<a href="../../api-guide/content-negotiation">Content negotiation</a>
</li>
......@@ -232,6 +236,10 @@
</li>
<li >
<a href="../internationalization">Internationalization</a>
</li>
<li >
<a href="../ajax-csrf-cors">AJAX, CSRF & CORS</a>
</li>
......@@ -259,36 +267,20 @@
<a href="../project-management">Project management</a>
</li>
<li >
<a href="../rest-framework-2-announcement">2.0 Announcement</a>
</li>
<li >
<a href="../2.2-announcement">2.2 Announcement</a>
</li>
<li >
<a href="../2.3-announcement">2.3 Announcement</a>
</li>
<li >
<a href="../2.4-announcement">2.4 Announcement</a>
</li>
<li class="active" >
<a href=".">3.0 Announcement</a>
</li>
<li >
<a href="../kickstarter-announcement">Kickstarter Announcement</a>
<a href="../3.1-announcement">3.1 Announcement</a>
</li>
<li >
<a href="../release-notes">Release Notes</a>
<a href="../kickstarter-announcement">Kickstarter Announcement</a>
</li>
<li >
<a href="../credits">Credits</a>
<a href="../release-notes">Release Notes</a>
</li>
</ul>
......
topics/2.4-announcement/index.html → topics/3.1-announcement/index.html
......@@ -4,11 +4,11 @@
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta charset="utf-8">
<title>2.4 Announcement - Django REST framework</title>
<title>3.1 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/2.4-announcement/" />
<link rel="canonical" href="http://www.django-rest-framework.org/topics/3.1-announcement/" />
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="description" content="Django, API, REST, 2.4 Announcement">
<meta name="description" content="Django, API, REST, 3.1 Announcement">
<meta name="author" content="Tom Christie">
<!-- Le styles -->
......@@ -62,10 +62,10 @@
<div class="navbar-inner">
<div class="container-fluid">
<a class="repo-link btn btn-primary btn-small" href="https://github.com/tomchristie/django-rest-framework/tree/master">GitHub</a>
<a class="repo-link btn btn-inverse btn-small " rel="prev" href="../3.0-announcement">
<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="../2.3-announcement">
<a class="repo-link btn btn-inverse btn-small " rel="next" href="../3.0-announcement">
<i class="icon-arrow-left icon-white"></i> Previous
</a>
<a class="repo-link btn btn-inverse btn-small" href="#searchModal" data-toggle="modal"><i class="icon-search icon-white"></i> Search</a>
......@@ -189,6 +189,10 @@
</li>
<li >
<a href="../../api-guide/versioning">Versioning</a>
</li>
<li >
<a href="../../api-guide/content-negotiation">Content negotiation</a>
</li>
......@@ -232,6 +236,10 @@
</li>
<li >
<a href="../internationalization">Internationalization</a>
</li>
<li >
<a href="../ajax-csrf-cors">AJAX, CSRF & CORS</a>
</li>
......@@ -260,23 +268,11 @@
</li>
<li >
<a href="../rest-framework-2-announcement">2.0 Announcement</a>
</li>
<li >
<a href="../2.2-announcement">2.2 Announcement</a>
</li>
<li >
<a href="../2.3-announcement">2.3 Announcement</a>
<a href="../3.0-announcement">3.0 Announcement</a>
</li>
<li class="active" >
<a href=".">2.4 Announcement</a>
</li>
<li >
<a href="../3.0-announcement">3.0 Announcement</a>
<a href=".">3.1 Announcement</a>
</li>
<li >
......@@ -287,10 +283,6 @@
<a href="../release-notes">Release Notes</a>
</li>
<li >
<a href="../credits">Credits</a>
</li>
</ul>
</li>
......@@ -353,36 +345,32 @@
<li class="main">
<a href="#django-rest-framework-24">Django REST framework 2.4</a>
<a href="#django-rest-framework-31">Django REST framework 3.1</a>
</li>
<li>
<a href="#version-requirements">Version requirements</a>
</li>
<li>
<a href="#django-17-support">Django 1.7 support</a>
<a href="#pagination">Pagination</a>
</li>
<li>
<a href="#deprecation-of-model-view-attribute">Deprecation of .model view attribute</a>
<a href="#versioning">Versioning</a>
</li>
<li>
<a href="#updated-test-runner">Updated test runner</a>
<a href="#internationalization">Internationalization</a>
</li>
<li>
<a href="#improved-viewset-routing">Improved viewset routing</a>
<a href="#new-field-types">New field types</a>
</li>
<li>
<a href="#throttle-behavior">Throttle behavior</a>
<a href="#modelserializer-api">ModelSerializer API</a>
</li>
<li>
<a href="#other-features">Other features</a>
<a href="#moving-packages-out-of-core">Moving packages out of core</a>
</li>
<li>
......@@ -390,11 +378,7 @@
</li>
<li>
<a href="#labels-and-milestones">Labels and milestones</a>
</li>
<li>
<a href="#next-steps">Next steps</a>
<a href="#whats-next">What's next?</a>
</li>
......@@ -410,113 +394,148 @@
<div id="main-content" class="span9">
<h1 id="django-rest-framework-24">Django REST framework 2.4</h1>
<p>The 2.4 release is largely an intermediate step, tying up some outstanding issues prior to the 3.x series.</p>
<h2 id="version-requirements">Version requirements</h2>
<p>Support for Django 1.3 has been dropped.
The lowest supported version of Django is now 1.4.2.</p>
<p>The current plan is for REST framework to remain in lockstep with <a href="https://docs.djangoproject.com/en/dev/internals/release-process/#long-term-support-lts-releases">Django's long-term support policy</a>.</p>
<h2 id="django-17-support">Django 1.7 support</h2>
<p>The optional authtoken application now includes support for <em>both</em> Django 1.7 schema migrations, <em>and</em> for old-style <code>south</code> migrations.</p>
<p><strong>If you are using authtoken, and you want to continue using <code>south</code>, you must upgrade your <code>south</code> package to version 1.0.</strong></p>
<h2 id="deprecation-of-model-view-attribute">Deprecation of <code>.model</code> view attribute</h2>
<p>The <code>.model</code> attribute on view classes is an optional shortcut for either or both of <code>.serializer_class</code> and <code>.queryset</code>. Its usage results in more implicit, less obvious behavior.</p>
<p>The documentation has previously stated that usage of the more explicit style is prefered, and we're now taking that one step further and deprecating the usage of the <code>.model</code> shortcut.</p>
<p>Doing so will mean that there are cases of API code where you'll now need to include a serializer class where you previously were just using the <code>.model</code> shortcut. However we firmly believe that it is the right trade-off to make.</p>
<p>Removing the shortcut takes away an unnecessary layer of abstraction, and makes your codebase more explicit without any significant extra complexity. It also results in better consistency, as there's now only one way to set the serializer class and queryset attributes for the view, instead of two.</p>
<p>The <code>DEFAULT_MODEL_SERIALIZER_CLASS</code> API setting is now also deprecated.</p>
<h2 id="updated-test-runner">Updated test runner</h2>
<p>We now have a new test runner for developing against the project,, that uses the excellent <a href="http://pytest.org">py.test</a> library.</p>
<p>To use it make sure you have first installed the test requirements.</p>
<pre><code>pip install -r requirements-test.txt
</code></pre>
<p>Then run the <code>runtests.py</code> script.</p>
<pre><code>./runtests.py
</code></pre>
<p>The new test runner also includes <a href="https://flake8.readthedocs.org">flake8</a> code linting, which should help keep our coding style consistent.</p>
<h4 id="test-runner-flags">Test runner flags</h4>
<p>Run using a more concise output style.</p>
<pre><code>./runtests -q
<h1 id="django-rest-framework-31">Django REST framework 3.1</h1>
<p>The 3.1 release is an intermediate step in the Kickstarter project releases, and includes a range of new functionality.</p>
<p>Some highlights include:</p>
<ul>
<li>A super-smart cursor pagination scheme.</li>
<li>An improved pagination API, supporting header or in-body pagination styles.</li>
<li>Pagination controls rendering in the browsable API.</li>
<li>Better support for API versioning.</li>
<li>Built-in internationalization support.</li>
<li>Support for Django 1.8's <code>HStoreField</code> and <code>ArrayField</code>.</li>
</ul>
<hr />
<h2 id="pagination">Pagination</h2>
<p>The pagination API has been improved, making it both easier to use, and more powerful.</p>
<p>A guide to the headline features follows. For full details, see <a href="../../api-guide/pagination">the pagination documentation</a>.</p>
<p>Note that as a result of this work a number of settings keys and generic view attributes are now moved to pending deprecation. Controlling pagination styles is now largely handled by overriding a pagination class and modifying its configuration attributes.</p>
<ul>
<li>The <code>PAGINATE_BY</code> settings key will continue to work but is now pending deprecation. The more obviously named <code>PAGE_SIZE</code> settings key should now be used instead.</li>
<li>The <code>PAGINATE_BY_PARAM</code>, <code>MAX_PAGINATE_BY</code> settings keys will continue to work but are now pending deprecation, in favor of setting configuration attributes on the configured pagination class.</li>
<li>The <code>paginate_by</code>, <code>page_query_param</code>, <code>paginate_by_param</code> and <code>max_paginate_by</code> generic view attributes will continue to work but are now pending deprecation, in favor of setting configuration attributes on the configured pagination class.</li>
<li>The <code>pagination_serializer_class</code> view attribute and <code>DEFAULT_PAGINATION_SERIALIZER_CLASS</code> settings key <strong>are no longer valid</strong>. The pagination API does not use serializers to determine the output format, and you'll need to instead override the <code>get_paginated_response</code> method on a pagination class in order to specify how the output format is controlled.</li>
</ul>
<h4 id="new-pagination-schemes">New pagination schemes.</h4>
<p>Until now, there has only been a single built-in pagination style in REST framework. We now have page, limit/offset and cursor based schemes included by default.</p>
<p>The cursor based pagination scheme is particularly smart, and is a better approach for clients iterating through large or frequently changing result sets. The scheme supports paging against non-unique indexes, by using both cursor and limit/offset information. It also allows for both forward and reverse cursor pagination. Much credit goes to David Cramer for <a href="http://cramer.io/2011/03/08/building-cursors-for-the-disqus-api/">this blog post</a> on the subject.</p>
<h4 id="pagination-controls-in-the-browsable-api">Pagination controls in the browsable API.</h4>
<p>Paginated results now include controls that render directly in the browsable API. If you're using the page or limit/offset style, then you'll see a page based control displayed in the browsable API:</p>
<p><img alt="page number based pagination" src="../../../img/pages-pagination.png" /></p>
<p>The cursor based pagination renders a more simple style of control:</p>
<p><img alt="cursor based pagination" src="../../../img/cursor-pagination.png" /></p>
<h4 id="support-for-header-based-pagination">Support for header-based pagination.</h4>
<p>The pagination API was previously only able to alter the pagination style in the body of the response. The API now supports being able to write pagination information in response headers, making it possible to use pagination schemes that use the <code>Link</code> or <code>Content-Range</code> headers.</p>
<p>For more information, see the <a href="../../../api-guide/pagination/#custom-pagination-styles">custom pagination styles</a> documentation.</p>
<hr />
<h2 id="versioning">Versioning</h2>
<p>We've made it easier to build versioned APIs. Built-in schemes for versioning include both URL based and Accept header based variations.</p>
<p>When using a URL based scheme, hyperlinked serializers will resolve relationships to the same API version as used on the incoming request.</p>
<p>For example, when using <code>NamespaceVersioning</code>, and the following hyperlinked serializer:</p>
<pre><code>class AccountsSerializer(serializer.HyperlinkedModelSerializer):
class Meta:
model = Accounts
fields = ('account_name', 'users')
</code></pre>
<p>Run the tests using a more concise output style, no coverage, no flake8.</p>
<pre><code>./runtests --fast
<p>The output representation would match the version used on the incoming request. Like so:</p>
<pre><code>GET http://example.org/v2/accounts/10 # Version 'v2'
{
"account_name": "europa",
"users": [
"http://example.org/v2/users/12", # Version 'v2'
"http://example.org/v2/users/54",
"http://example.org/v2/users/87"
]
}
</code></pre>
<p>Don't run the flake8 code linting.</p>
<pre><code>./runtests --nolint
<hr />
<h2 id="internationalization">Internationalization</h2>
<p>REST framework now includes a built-in set of translations, and supports internationalized error responses. This allows you to either change the default language, or to allow clients to specify the language via the <code>Accept-Language</code> header.</p>
<p>You can change the default language by using the standard Django <code>LANGUAGE_CODE</code> setting:</p>
<pre><code>LANGUAGE_CODE = "es-es"
</code></pre>
<p>Only run the flake8 code linting, don't run the tests.</p>
<pre><code>./runtests --lintonly
<p>You can turn on per-request language requests by adding <code>LocalMiddleware</code> to your <code>MIDDLEWARE_CLASSES</code> setting:</p>
<pre><code>MIDDLEWARE_CLASSES = [
...
'django.middleware.locale.LocaleMiddleware'
]
</code></pre>
<p>Run the tests for a given test case.</p>
<pre><code>./runtests MyTestCase
<p>When per-request internationalization is enabled, client requests will respect the <code>Accept-Language</code> header where possible. For example, let's make a request for an unsupported media type:</p>
<p><strong>Request</strong></p>
<pre><code>GET /api/users HTTP/1.1
Accept: application/xml
Accept-Language: es-es
Host: example.org
</code></pre>
<p>Run the tests for a given test method.</p>
<pre><code>./runtests MyTestCase.test_this_method
<p><strong>Response</strong></p>
<pre><code>HTTP/1.0 406 NOT ACCEPTABLE
{
"detail": "No se ha podido satisfacer la solicitud de cabecera de Accept."
}
</code></pre>
<p>Shorter form to run the tests for a given test method.</p>
<pre><code>./runtests test_this_method
<p>Note that the structure of the error responses is still the same. We still have a <code>details</code> key in the response. If needed you can modify this behavior too, by using a <a href="../../api-guide/exceptions#custom-exception-handling">custom exception handler</a>.</p>
<p>We include built-in translations both for standard exception cases, and for serializer validation errors.</p>
<p>The full list of supported languages can be found on our <a href="https://www.transifex.com/projects/p/django-rest-framework/">Transifex project page</a>.</p>
<p>If you only wish to support a subset of the supported languages, use Django's standard <code>LANGUAGES</code> setting:</p>
<pre><code>LANGUAGES = [
('de', _('German')),
('en', _('English')),
]
</code></pre>
<p>Note: The test case and test method matching is fuzzy and will sometimes run other tests that contain a partial string match to the given command line input.</p>
<h2 id="improved-viewset-routing">Improved viewset routing</h2>
<p>The <code>@action</code> and <code>@link</code> decorators were inflexible in that they only allowed additional routes to be added against instance style URLs, not against list style URLs.</p>
<p>The <code>@action</code> and <code>@link</code> decorators have now been moved to pending deprecation, and the <code>@list_route</code> and <code>@detail_route</code> decorators have been introduced.</p>
<p>Here's an example of using the new decorators. Firstly we have a detail-type route named "set_password" that acts on a single instance, and takes a <code>pk</code> argument in the URL. Secondly we have a list-type route named "recent_users" that acts on a queryset, and does not take any arguments in the URL.</p>
<pre><code>class UserViewSet(viewsets.ModelViewSet):
"""
A viewset that provides the standard actions
"""
queryset = User.objects.all()
serializer_class = UserSerializer
@detail_route(methods=['post'])
def set_password(self, request, pk=None):
user = self.get_object()
serializer = PasswordSerializer(data=request.DATA)
if serializer.is_valid():
user.set_password(serializer.data['password'])
user.save()
return Response({'status': 'password set'})
else:
return Response(serializer.errors,
status=status.HTTP_400_BAD_REQUEST)
@list_route()
def recent_users(self, request):
recent_users = User.objects.all().order('-last_login')
page = self.paginate_queryset(recent_users)
serializer = self.get_pagination_serializer(page)
return Response(serializer.data)
<p>For more details, see the <a href="../internationalization">internationalization documentation</a>.</p>
<p>Many thanks to <a href="https://github.com/jakul">Craig Blaszczyk</a> for helping push this through.</p>
<hr />
<h2 id="new-field-types">New field types</h2>
<p>Django 1.8's new <code>ArrayField</code>, <code>HStoreField</code> and <code>UUIDField</code> are now all fully supported.</p>
<p>This work also means that we now have both <code>serializers.DictField()</code>, and <code>serializers.ListField()</code> types, allowing you to express and validate a wider set of representations.</p>
<p>If you're building a new 1.8 project, then you should probably consider using <code>UUIDField</code> as the primary keys for all your models. This style will work automatically with hyperlinked serializers, returning URLs in the following style:</p>
<pre><code>http://example.org/api/purchases/9b1a433f-e90d-4948-848b-300fdc26365d
</code></pre>
<p>For more details, see the <a href="../../api-guide/viewsets">viewsets documentation</a>.</p>
<h2 id="throttle-behavior">Throttle behavior</h2>
<p>There's one bugfix in 2.4 that's worth calling out, as it will <em>invalidate existing throttle caches</em> when you upgrade.</p>
<p>We've now fixed a typo on the <code>cache_format</code> attribute. Previously this was named <code>"throtte_%(scope)s_%(ident)s"</code>, it is now <code>"throttle_%(scope)s_%(ident)s"</code>.</p>
<p>If you're concerned about the invalidation you have two options.</p>
<hr />
<h2 id="modelserializer-api">ModelSerializer API</h2>
<p>The serializer redesign in 3.0 did not include any public API for modifying how ModelSerializer classes automatically generate a set of fields from a given mode class. We've now re-introduced an API for this, allowing you to create new ModelSerializer base classes that behave differently, such as using a different default style for relationships.</p>
<p>For more information, see the documentation on <a href="../../../api-guide/serializers/#customizing-field-mappings">customizing field mappings</a> for ModelSerializer classes.</p>
<hr />
<h2 id="moving-packages-out-of-core">Moving packages out of core</h2>
<p>We've now moved a number of packages out of the core of REST framework, and into separately installable packages. If you're currently using these you don't need to worry, you simply need to <code>pip install</code> the new packages, and change any import paths.</p>
<p>We're making this change in order to help distribute the maintainance workload, and keep better focus of the core essentials of the framework.</p>
<p>The change also means we can be more flexible with which external packages we recommend. For example, the excellently maintained <a href="https://github.com/evonove/django-oauth-toolkit">Django OAuth toolkit</a> has now been promoted as our recommended option for integrating OAuth support.</p>
<p>The following packages are now moved out of core and should be separately installed:</p>
<ul>
<li>Manually pre-populate your cache with the fixed version.</li>
<li>Set the <code>cache_format</code> attribute on your throttle class in order to retain the previous incorrect spelling.</li>
<li>OAuth - <a href="http://jpadilla.github.io/django-rest-framework-oauth/">djangorestframework-oauth</a></li>
<li>XML - <a href="http://jpadilla.github.io/django-rest-framework-xml">djangorestframework-xml</a></li>
<li>YAML - <a href="http://jpadilla.github.io/django-rest-framework-yaml">djangorestframework-yaml</a></li>
<li>JSONP - <a href="http://jpadilla.github.io/django-rest-framework-jsonp">djangorestframework-jsonp</a></li>
</ul>
<h2 id="other-features">Other features</h2>
<p>There are also a number of other features and bugfixes as <a href="../../release-notes#240">listed in the release notes</a>. In particular these include:</p>
<p><a href="../../../api-guide/settings#view-names-and-descriptions">Customizable view name and description functions</a> for use with the browsable API, by using the <code>VIEW_NAME_FUNCTION</code> and <code>VIEW_DESCRIPTION_FUNCTION</code> settings.</p>
<p>Smarter <a href="../../../api-guide/throttling#how-clients-are-identified">client IP identification for throttling</a>, with the addition of the <code>NUM_PROXIES</code> setting.</p>
<p>Added the standardized <code>Retry-After</code> header to throttled responses, as per <a href="http://tools.ietf.org/html/rfc6585">RFC 6585</a>. This should now be used in preference to the custom <code>X-Throttle-Wait-Seconds</code> header which will be fully deprecated in 3.0.</p>
<h2 id="deprecations">Deprecations</h2>
<p>All API changes in 2.3 that previously raised <code>PendingDeprecationWarning</code> will now raise a <code>DeprecationWarning</code>, which is loud by default.</p>
<p>All API changes in 2.3 that previously raised <code>DeprecationWarning</code> have now been removed entirely.</p>
<p>Furter details on these deprecations is available in the <a href="../../2.3-announcement">2.3 announcement</a>.</p>
<h2 id="labels-and-milestones">Labels and milestones</h2>
<p>Although not strictly part of the 2.4 release it's also worth noting here that we've been working hard towards improving our triage process.</p>
<p>The <a href="https://github.com/tomchristie/django-rest-framework/issues">labels that we use in GitHub</a> have been cleaned up, and all existing tickets triaged. Any given ticket should have one and only one label, indicating its current state.</p>
<p>We've also <a href="https://github.com/tomchristie/django-rest-framework/milestones">started using milestones</a> in order to track tickets against particular releases.</p>
<p>It's worth reiterating that this change in policy shouldn't mean any work in your codebase other than adding a new requirement and modifying some import paths. For example to install XML rendering, you would now do:</p>
<pre><code>pip install djangorestframework-xml
</code></pre>
<p>And modify your settings, like so:</p>
<pre><code>REST_FRAMEWORK = {
'DEFAULT_RENDERER_CLASSES': [
'rest_framework.renderers.JSONRenderer',
'rest_framework.renderers.BrowsableAPIRenderer',
'rest_framework_xml.renderers.XMLRenderer'
]
}
</code></pre>
<p>Thanks go to the latest member of our maintenance team, <a href="https://github.com/jpadilla/">José Padilla</a>, for handling this work and taking on ownership of these packages.</p>
<hr />
<p><img alt="Labels and milestones" src="../../../img/labels-and-milestones.png" /></p>
<p><strong>Above</strong>: <em>Overview of our current use of labels and milestones in GitHub.</em></p>
<h2 id="deprecations">Deprecations</h2>
<p>The <code>request.DATA</code>, <code>request.FILES</code> and <code>request.QUERY_PARAMS</code> attributes move from pending deprecation, to deprecated. Use <code>request.data</code> and <code>request.query_params</code> instead, as discussed in the 3.0 release notes.</p>
<p>The ModelSerializer Meta options for <code>write_only_fields</code>, <code>view_name</code> and <code>lookup_field</code> are also moved from pending deprecation, to deprecated. Use <code>extra_kwargs</code> instead, as discussed in the 3.0 release notes.</p>
<p>All these attributes and options will still work in 3.1, but their usage will raise a warning. They will be fully removed in 3.2.</p>
<hr />
<p>We hope both of these changes will help make the management process more clear and obvious and help keep tickets well-organised and relevant.</p>
<h2 id="next-steps">Next steps</h2>
<p>The next planned release will be 3.0, featuring an improved and simplified serializer implementation.</p>
<p>Once again, many thanks to all the generous <a href="../../kickstarter-announcement#sponsors">backers and sponsors</a> who've helped make this possible!</p>
<h2 id="whats-next">What's next?</h2>
<p>The next focus will be on HTML renderings of API output and will include:</p>
<ul>
<li>HTML form rendering of serializers.</li>
<li>Filtering controls built-in to the browsable API.</li>
<li>An alternative admin-style interface.</li>
</ul>
<p>This will either be made as a single 3.2 release, or split across two separate releases, with the HTML forms and filter controls coming in 3.2, and the admin-style interface coming in a 3.3 release.</p>
</div>
<!--/span-->
......
topics/ajax-csrf-cors/index.html
......@@ -65,7 +65,7 @@
<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="../documenting-your-api">
<a class="repo-link btn btn-inverse btn-small " rel="next" href="../internationalization">
<i class="icon-arrow-left icon-white"></i> Previous
</a>
<a class="repo-link btn btn-inverse btn-small" href="#searchModal" data-toggle="modal"><i class="icon-search icon-white"></i> Search</a>
......@@ -189,6 +189,10 @@
</li>
<li >
<a href="../../api-guide/versioning">Versioning</a>
</li>
<li >
<a href="../../api-guide/content-negotiation">Content negotiation</a>
</li>
......@@ -231,6 +235,10 @@
<a href="../documenting-your-api">Documenting your API</a>
</li>
<li >
<a href="../internationalization">Internationalization</a>
</li>
<li class="active" >
<a href=".">AJAX, CSRF & CORS</a>
</li>
......@@ -260,23 +268,11 @@
</li>
<li >
<a href="../rest-framework-2-announcement">2.0 Announcement</a>
</li>
<li >
<a href="../2.2-announcement">2.2 Announcement</a>
</li>
<li >
<a href="../2.3-announcement">2.3 Announcement</a>
</li>
<li >
<a href="../2.4-announcement">2.4 Announcement</a>
<a href="../3.0-announcement">3.0 Announcement</a>
</li>
<li >
<a href="../3.0-announcement">3.0 Announcement</a>
<a href="../3.1-announcement">3.1 Announcement</a>
</li>
<li >
......@@ -287,10 +283,6 @@
<a href="../release-notes">Release Notes</a>
</li>
<li >
<a href="../credits">Credits</a>
</li>
</ul>
</li>
......
topics/browsable-api/index.html
......@@ -189,6 +189,10 @@
</li>
<li >
<a href="../../api-guide/versioning">Versioning</a>
</li>
<li >
<a href="../../api-guide/content-negotiation">Content negotiation</a>
</li>
......@@ -232,6 +236,10 @@
</li>
<li >
<a href="../internationalization">Internationalization</a>
</li>
<li >
<a href="../ajax-csrf-cors">AJAX, CSRF & CORS</a>
</li>
......@@ -260,23 +268,11 @@
</li>
<li >
<a href="../rest-framework-2-announcement">2.0 Announcement</a>
</li>
<li >
<a href="../2.2-announcement">2.2 Announcement</a>
</li>
<li >
<a href="../2.3-announcement">2.3 Announcement</a>
</li>
<li >
<a href="../2.4-announcement">2.4 Announcement</a>
<a href="../3.0-announcement">3.0 Announcement</a>
</li>
<li >
<a href="../3.0-announcement">3.0 Announcement</a>
<a href="../3.1-announcement">3.1 Announcement</a>
</li>
<li >
......@@ -287,10 +283,6 @@
<a href="../release-notes">Release Notes</a>
</li>
<li >
<a href="../credits">Credits</a>
</li>
</ul>
</li>
......
topics/browser-enhancements/index.html
......@@ -189,6 +189,10 @@
</li>
<li >
<a href="../../api-guide/versioning">Versioning</a>
</li>
<li >
<a href="../../api-guide/content-negotiation">Content negotiation</a>
</li>
......@@ -232,6 +236,10 @@
</li>
<li >
<a href="../internationalization">Internationalization</a>
</li>
<li >
<a href="../ajax-csrf-cors">AJAX, CSRF & CORS</a>
</li>
......@@ -260,23 +268,11 @@
</li>
<li >
<a href="../rest-framework-2-announcement">2.0 Announcement</a>
</li>
<li >
<a href="../2.2-announcement">2.2 Announcement</a>
</li>
<li >
<a href="../2.3-announcement">2.3 Announcement</a>
</li>
<li >
<a href="../2.4-announcement">2.4 Announcement</a>
<a href="../3.0-announcement">3.0 Announcement</a>
</li>
<li >
<a href="../3.0-announcement">3.0 Announcement</a>
<a href="../3.1-announcement">3.1 Announcement</a>
</li>
<li >
......@@ -287,10 +283,6 @@
<a href="../release-notes">Release Notes</a>
</li>
<li >
<a href="../credits">Credits</a>
</li>
</ul>
</li>
......
topics/contributing/index.html
......@@ -189,6 +189,10 @@
</li>
<li >
<a href="../../api-guide/versioning">Versioning</a>
</li>
<li >
<a href="../../api-guide/content-negotiation">Content negotiation</a>
</li>
......@@ -232,6 +236,10 @@
</li>
<li >
<a href="../internationalization">Internationalization</a>
</li>
<li >
<a href="../ajax-csrf-cors">AJAX, CSRF & CORS</a>
</li>
......@@ -260,23 +268,11 @@
</li>
<li >
<a href="../rest-framework-2-announcement">2.0 Announcement</a>
</li>
<li >
<a href="../2.2-announcement">2.2 Announcement</a>
</li>
<li >
<a href="../2.3-announcement">2.3 Announcement</a>
</li>
<li >
<a href="../2.4-announcement">2.4 Announcement</a>
<a href="../3.0-announcement">3.0 Announcement</a>
</li>
<li >
<a href="../3.0-announcement">3.0 Announcement</a>
<a href="../3.1-announcement">3.1 Announcement</a>
</li>
<li >
......@@ -287,10 +283,6 @@
<a href="../release-notes">Release Notes</a>
</li>
<li >
<a href="../credits">Credits</a>
</li>
</ul>
</li>
......
topics/credits/index.html deleted 100644 → 0
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta charset="utf-8">
<title>Credits - 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/credits/" />
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="description" content="Django, API, REST, Credits">
<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 disabled" rel="prev" >
Next <i class="icon-arrow-right icon-white"></i>
</a>
<a class="repo-link btn btn-inverse btn-small " rel="next" href="../release-notes">
<i class="icon-arrow-left icon-white"></i> Previous
</a>
<a class="repo-link btn btn-inverse btn-small" href="#searchModal" data-toggle="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/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="../ajax-csrf-cors">AJAX, CSRF & CORS</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="../rest-framework-2-announcement">2.0 Announcement</a>
</li>
<li >
<a href="../2.2-announcement">2.2 Announcement</a>
</li>
<li >
<a href="../2.3-announcement">2.3 Announcement</a>
</li>
<li >
<a href="../2.4-announcement">2.4 Announcement</a>
</li>
<li >
<a href="../3.0-announcement">3.0 Announcement</a>
</li>
<li >
<a href="../kickstarter-announcement">Kickstarter Announcement</a>
</li>
<li >
<a href="../release-notes">Release Notes</a>
</li>
<li class="active" >
<a href=".">Credits</a>
</li>
</ul>
</li>
</ul>
</div>
<!--/.nav-collapse -->
</div>
</div>
</div>
<div class="body-content">
<div class="container-fluid">
<!-- Search Modal -->
<div id="searchModal" 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">
<!-- Custom google search -->
<script>
(function() {
var cx = '015016005043623903336:rxraeohqk6w';
var gcse = document.createElement('script');
gcse.type = 'text/javascript';
gcse.async = true;
gcse.src = (document.location.protocol == 'https:' ? 'https:' : 'http:') +
'//www.google.com/cse/cse.js?cx=' + cx;
var s = document.getElementsByTagName('script')[0];
s.parentNode.insertBefore(gcse, s);
})();
</script>
<gcse:search></gcse:search>
</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">
<!-- TODO
<p style="margin-top: -12px">
<a class="btn btn-mini btn-primary" style="width: 60px">&laquo; previous</a>
<a class="btn btn-mini btn-primary" style="float: right; margin-right: 8px; width: 60px;">next &raquo;</a>
</p>
-->
<div id="table-of-contents">
<ul class="nav nav-list side-nav well sidebar-nav-fixed">
<li class="main">
<a href="#credits">Credits</a>
</li>
<li>
<a href="#additional-thanks">Additional thanks</a>
</li>
<li>
<a href="#contact">Contact</a>
</li>
</ul>
</div>
</div>
<div id="main-content" class="span9">
<h1 id="credits">Credits</h1>
<p>The following people have helped make REST framework great.</p>
<ul>
<li>Tom Christie - <a href="https://github.com/tomchristie">tomchristie</a></li>
<li>Marko Tibold - <a href="https://github.com/markotibold">markotibold</a></li>
<li>Paul Miller - <a href="https://github.com/paulmillr">paulmillr</a></li>
<li>Sébastien Piquemal - <a href="https://github.com/sebpiq">sebpiq</a></li>
<li>Carmen Wick - <a href="https://github.com/cwick">cwick</a></li>
<li>Alex Ehlke - <a href="https://github.com/aehlke">aehlke</a></li>
<li>Alen Mujezinovic - <a href="https://github.com/flashingpumpkin">flashingpumpkin</a></li>
<li>Carles Barrobés - <a href="https://github.com/txels">txels</a></li>
<li>Michael Fötsch - <a href="https://github.com/mfoetsch">mfoetsch</a></li>
<li>David Larlet - <a href="https://github.com/david">david</a></li>
<li>Andrew Straw - <a href="https://github.com/astraw">astraw</a></li>
<li>Zeth - <a href="https://github.com/zeth">zeth</a></li>
<li>Fernando Zunino - <a href="https://github.com/fzunino">fzunino</a></li>
<li>Jens Alm - <a href="https://github.com/ulmus">ulmus</a></li>
<li>Craig Blaszczyk - <a href="https://github.com/jakul">jakul</a></li>
<li>Garcia Solero - <a href="https://github.com/garciasolero">garciasolero</a></li>
<li>Tom Drummond - <a href="https://github.com/devioustree">devioustree</a></li>
<li>Danilo Bargen - <a href="https://github.com/dbrgn">dbrgn</a></li>
<li>Andrew McCloud - <a href="https://github.com/amccloud">amccloud</a></li>
<li>Thomas Steinacher - <a href="https://github.com/thomasst">thomasst</a></li>
<li>Meurig Freeman - <a href="https://github.com/meurig">meurig</a></li>
<li>Anthony Nemitz - <a href="https://github.com/anemitz">anemitz</a></li>
<li>Ewoud Kohl van Wijngaarden - <a href="https://github.com/ekohl">ekohl</a></li>
<li>Michael Ding - <a href="https://github.com/yandy">yandy</a></li>
<li>Mjumbe Poe - <a href="https://github.com/mjumbewu">mjumbewu</a></li>
<li>Natim - <a href="https://github.com/natim">natim</a></li>
<li>Sebastian Żurek - <a href="https://github.com/sebzur">sebzur</a></li>
<li>Benoit C - <a href="https://github.com/dzen">dzen</a></li>
<li>Chris Pickett - <a href="https://github.com/bunchesofdonald">bunchesofdonald</a></li>
<li>Ben Timby - <a href="https://github.com/btimby">btimby</a></li>
<li>Michele Lazzeri - <a href="https://github.com/michelelazzeri-nextage">michelelazzeri-nextage</a></li>
<li>Camille Harang - <a href="https://github.com/mammique">mammique</a></li>
<li>Paul Oswald - <a href="https://github.com/poswald">poswald</a></li>
<li>Sean C. Farley - <a href="https://github.com/scfarley">scfarley</a></li>
<li>Daniel Izquierdo - <a href="https://github.com/izquierdo">izquierdo</a></li>
<li>Can Yavuz - <a href="https://github.com/tschan">tschan</a></li>
<li>Shawn Lewis - <a href="https://github.com/shawnlewis">shawnlewis</a></li>
<li>Alec Perkins - <a href="https://github.com/alecperkins">alecperkins</a></li>
<li>Michael Barrett - <a href="https://github.com/phobologic">phobologic</a></li>
<li>Mathieu Dhondt - <a href="https://github.com/laundromat">laundromat</a></li>
<li>Johan Charpentier - <a href="https://github.com/cyberj">cyberj</a></li>
<li>Jamie Matthews - <a href="https://github.com/j4mie">j4mie</a></li>
<li>Mattbo - <a href="https://github.com/mattbo">mattbo</a></li>
<li>Max Hurl - <a href="https://github.com/maximilianhurl">maximilianhurl</a></li>
<li>Tomi Pajunen - <a href="https://github.com/eofs">eofs</a></li>
<li>Rob Dobson - <a href="https://github.com/rdobson">rdobson</a></li>
<li>Daniel Vaca Araujo - <a href="https://github.com/diviei">diviei</a></li>
<li>Madis Väin - <a href="https://github.com/madisvain">madisvain</a></li>
<li>Stephan Groß - <a href="https://github.com/minddust">minddust</a></li>
<li>Pavel Savchenko - <a href="https://github.com/asfaltboy">asfaltboy</a></li>
<li>Otto Yiu - <a href="https://github.com/OttoYiu">ottoyiu</a></li>
<li>Jacob Magnusson - <a href="https://github.com/jmagnusson">jmagnusson</a></li>
<li>Osiloke Harold Emoekpere - <a href="https://github.com/osiloke">osiloke</a></li>
<li>Michael Shepanski - <a href="https://github.com/mjs7231">mjs7231</a></li>
<li>Toni Michel - <a href="https://github.com/tonimichel">tonimichel</a></li>
<li>Ben Konrath - <a href="https://github.com/benkonrath">benkonrath</a></li>
<li>Marc Aymerich - <a href="https://github.com/glic3rinu">glic3rinu</a></li>
<li>Ludwig Kraatz - <a href="https://github.com/ludwigkraatz">ludwigkraatz</a></li>
<li>Rob Romano - <a href="https://github.com/robromano">robromano</a></li>
<li>Eugene Mechanism - <a href="https://github.com/mechanism">mechanism</a></li>
<li>Jonas Liljestrand - <a href="https://github.com/jonlil">jonlil</a></li>
<li>Justin Davis - <a href="https://github.com/irrelative">irrelative</a></li>
<li>Dustin Bachrach - <a href="https://github.com/dbachrach">dbachrach</a></li>
<li>Mark Shirley - <a href="https://github.com/maspwr">maspwr</a></li>
<li>Olivier Aubert - <a href="https://github.com/oaubert">oaubert</a></li>
<li>Yuri Prezument - <a href="https://github.com/yprez">yprez</a></li>
<li>Fabian Buechler - <a href="https://github.com/fabianbuechler">fabianbuechler</a></li>
<li>Mark Hughes - <a href="https://github.com/mhsparks">mhsparks</a></li>
<li>Michael van de Waeter - <a href="https://github.com/mvdwaeter">mvdwaeter</a></li>
<li>Reinout van Rees - <a href="https://github.com/reinout">reinout</a></li>
<li>Michael Richards - <a href="https://github.com/justanotherbody">justanotherbody</a></li>
<li>Ben Roberts - <a href="https://github.com/roberts81">roberts81</a></li>
<li>Venkata Subramanian Mahalingam - <a href="https://github.com/annacoder">annacoder</a></li>
<li>George Kappel - <a href="https://github.com/gkappel">gkappel</a></li>
<li>Colin Murtaugh - <a href="https://github.com/cmurtaugh">cmurtaugh</a></li>
<li>Simon Pantzare - <a href="https://github.com/pilt">pilt</a></li>
<li>Szymon Teżewski - <a href="https://github.com/sunscrapers">sunscrapers</a></li>
<li>Joel Marcotte - <a href="https://github.com/joual">joual</a></li>
<li>Trey Hunner - <a href="https://github.com/treyhunner">treyhunner</a></li>
<li>Roman Akinfold - <a href="https://github.com/akinfold">akinfold</a></li>
<li>Toran Billups - <a href="https://github.com/toranb">toranb</a></li>
<li>Sébastien Béal - <a href="https://github.com/sebastibe">sebastibe</a></li>
<li>Andrew Hankinson - <a href="https://github.com/ahankinson">ahankinson</a></li>
<li>Juan Riaza - <a href="https://github.com/juanriaza">juanriaza</a></li>
<li>Michael Mior - <a href="https://github.com/michaelmior">michaelmior</a></li>
<li>Marc Tamlyn - <a href="https://github.com/mjtamlyn">mjtamlyn</a></li>
<li>Richard Wackerbarth - <a href="https://github.com/wackerbarth">wackerbarth</a></li>
<li>Johannes Spielmann - <a href="https://github.com/shezi">shezi</a></li>
<li>James Cleveland - <a href="https://github.com/radiosilence">radiosilence</a></li>
<li>Steve Gregory - <a href="https://github.com/steve-gregory">steve-gregory</a></li>
<li>Federico Capoano - <a href="https://github.com/nemesisdesign">nemesisdesign</a></li>
<li>Bruno Renié - <a href="https://github.com/brutasse">brutasse</a></li>
<li>Kevin Stone - <a href="https://github.com/kevinastone">kevinastone</a></li>
<li>Guglielmo Celata - <a href="https://github.com/guglielmo">guglielmo</a></li>
<li>Mike Tums - <a href="https://github.com/mktums">mktums</a></li>
<li>Michael Elovskikh - <a href="https://github.com/wronglink">wronglink</a></li>
<li>Michał Jaworski - <a href="https://github.com/swistakm">swistakm</a></li>
<li>Andrea de Marco - <a href="https://github.com/z4r">z4r</a></li>
<li>Fernando Rocha - <a href="https://github.com/fernandogrd">fernandogrd</a></li>
<li>Xavier Ordoquy - <a href="https://github.com/xordoquy">xordoquy</a></li>
<li>Adam Wentz - <a href="https://github.com/floppya">floppya</a></li>
<li>Andreas Pelme - <a href="https://github.com/pelme">pelme</a></li>
<li>Ryan Detzel - <a href="https://github.com/ryanrdetzel">ryanrdetzel</a></li>
<li>Omer Katz - <a href="https://github.com/thedrow">thedrow</a></li>
<li>Wiliam Souza - <a href="https://github.com/wiliamsouza">waa</a></li>
<li>Jonas Braun - <a href="https://github.com/iekadou">iekadou</a></li>
<li>Ian Dash - <a href="https://github.com/bitmonkey">bitmonkey</a></li>
<li>Bouke Haarsma - <a href="https://github.com/bouke">bouke</a></li>
<li>Pierre Dulac - <a href="https://github.com/dulaccc">dulaccc</a></li>
<li>Dave Kuhn - <a href="https://github.com/kuhnza">kuhnza</a></li>
<li>Sitong Peng - <a href="https://github.com/stoneg">stoneg</a></li>
<li>Victor Shih - <a href="https://github.com/vshih">vshih</a></li>
<li>Atle Frenvik Sveen - <a href="https://github.com/atlefren">atlefren</a></li>
<li>J Paul Reed - <a href="https://github.com/preed">preed</a></li>
<li>Matt Majewski - <a href="https://github.com/forgingdestiny">forgingdestiny</a></li>
<li>Jerome Chen - <a href="https://github.com/chenjyw">chenjyw</a></li>
<li>Andrew Hughes - <a href="https://github.com/eyepulp">eyepulp</a></li>
<li>Daniel Hepper - <a href="https://github.com/dhepper">dhepper</a></li>
<li>Hamish Campbell - <a href="https://github.com/hamishcampbell">hamishcampbell</a></li>
<li>Marlon Bailey - <a href="https://github.com/avinash240">avinash240</a></li>
<li>James Summerfield - <a href="https://github.com/jsummerfield">jsummerfield</a></li>
<li>Andy Freeland - <a href="https://github.com/rouge8">rouge8</a></li>
<li>Craig de Stigter - <a href="https://github.com/craigds">craigds</a></li>
<li>Pablo Recio - <a href="https://github.com/pyriku">pyriku</a></li>
<li>Brian Zambrano - <a href="https://github.com/brianz">brianz</a></li>
<li>Òscar Vilaplana - <a href="https://github.com/grimborg">grimborg</a></li>
<li>Ryan Kaskel - <a href="https://github.com/ryankask">ryankask</a></li>
<li>Andy McKay - <a href="https://github.com/andymckay">andymckay</a></li>
<li>Matteo Suppo - <a href="https://github.com/matteosuppo">matteosuppo</a></li>
<li>Karol Majta - <a href="https://github.com/lolek09">lolek09</a></li>
<li>David Jones - <a href="https://github.com/commonorgarden">commonorgarden</a></li>
<li>Andrew Tarzwell - <a href="https://github.com/atarzwell">atarzwell</a></li>
<li>Michal Dvořák - <a href="https://github.com/mikee2185">mikee2185</a></li>
<li>Markus Törnqvist - <a href="https://github.com/mjtorn">mjtorn</a></li>
<li>Pascal Borreli - <a href="https://github.com/pborreli">pborreli</a></li>
<li>Alex Burgel - <a href="https://github.com/aburgel">aburgel</a></li>
<li>David Medina - <a href="https://github.com/copitux">copitux</a></li>
<li>Areski Belaid - <a href="https://github.com/areski">areski</a></li>
<li>Ethan Freman - <a href="https://github.com/mindlace">mindlace</a></li>
<li>David Sanders - <a href="https://github.com/davesque">davesque</a></li>
<li>Philip Douglas - <a href="https://github.com/freakydug">freakydug</a></li>
<li>Igor Kalat - <a href="https://github.com/trwired">trwired</a></li>
<li>Rudolf Olah - <a href="https://github.com/omouse">omouse</a></li>
<li>Gertjan Oude Lohuis - <a href="https://github.com/gertjanol">gertjanol</a></li>
<li>Matthias Jacob - <a href="https://github.com/cyroxx">cyroxx</a></li>
<li>Pavel Zinovkin - <a href="https://github.com/pzinovkin">pzinovkin</a></li>
<li>Will Kahn-Greene - <a href="https://github.com/willkg">willkg</a></li>
<li>Kevin Brown - <a href="https://github.com/kevin-brown">kevin-brown</a></li>
<li>Rodrigo Martell - <a href="https://github.com/coderigo">coderigo</a></li>
<li>James Rutherford - <a href="https://github.com/jimr">jimr</a></li>
<li>Ricky Rosario - <a href="https://github.com/rlr">rlr</a></li>
<li>Veronica Lynn - <a href="https://github.com/kolvia">kolvia</a></li>
<li>Dan Stephenson - <a href="https://github.com/etos">etos</a></li>
<li>Martin Clement - <a href="https://github.com/martync">martync</a></li>
<li>Jeremy Satterfield - <a href="https://github.com/jsatt">jsatt</a></li>
<li>Christopher Paolini - <a href="https://github.com/chrispaolini">chrispaolini</a></li>
<li>Filipe A Ximenes - <a href="https://github.com/filipeximenes">filipeximenes</a></li>
<li>Ramiro Morales - <a href="https://github.com/ramiro">ramiro</a></li>
<li>Krzysztof Jurewicz - <a href="https://github.com/krzysiekj">krzysiekj</a></li>
<li>Eric Buehl - <a href="https://github.com/ericbuehl">ericbuehl</a></li>
<li>Kristian Øllegaard - <a href="https://github.com/kristianoellegaard">kristianoellegaard</a></li>
<li>Alexander Akhmetov - <a href="https://github.com/alexander-akhmetov">alexander-akhmetov</a></li>
<li>Andrey Antukh - <a href="https://github.com/niwibe">niwibe</a></li>
<li>Mathieu Pillard - <a href="https://github.com/diox">diox</a></li>
<li>Edmond Wong - <a href="https://github.com/edmondwong">edmondwong</a></li>
<li>Ben Reilly - <a href="https://github.com/bwreilly">bwreilly</a></li>
<li>Tai Lee - <a href="https://github.com/mrmachine">mrmachine</a></li>
<li>Markus Kaiserswerth - <a href="https://github.com/mkai">mkai</a></li>
<li>Henry Clifford - <a href="https://github.com/hcliff">hcliff</a></li>
<li>Thomas Badaud - <a href="https://github.com/badale">badale</a></li>
<li>Colin Huang - <a href="https://github.com/tamakisquare">tamakisquare</a></li>
<li>Ross McFarland - <a href="https://github.com/ross">ross</a></li>
<li>Jacek Bzdak - <a href="https://github.com/jbzdak">jbzdak</a></li>
<li>Alexander Lukanin - <a href="https://github.com/alexanderlukanin13">alexanderlukanin13</a></li>
<li>Yamila Moreno - <a href="https://github.com/yamila-moreno">yamila-moreno</a></li>
<li>Rob Hudson - <a href="https://github.com/robhudson">robhudson</a></li>
<li>Alex Good - <a href="https://github.com/alexjg">alexjg</a></li>
<li>Ian Foote - <a href="https://github.com/ian-foote">ian-foote</a></li>
<li>Chuck Harmston - <a href="https://github.com/chuckharmston">chuckharmston</a></li>
<li>Philip Forget - <a href="https://github.com/philipforget">philipforget</a></li>
<li>Artem Mezhenin - <a href="https://github.com/amezhenin">amezhenin</a></li>
</ul>
<p>Many thanks to everyone who's contributed to the project.</p>
<h2 id="additional-thanks">Additional thanks</h2>
<p>The documentation is built with <a href="http://twitter.github.com/bootstrap/">Bootstrap</a> and <a href="http://daringfireball.net/projects/markdown/">Markdown</a>.</p>
<p>Project hosting is with <a href="https://github.com/tomchristie/django-rest-framework">GitHub</a>.</p>
<p>Continuous integration testing is managed with <a href="https://secure.travis-ci.org/tomchristie/django-rest-framework">Travis CI</a>.</p>
<p>The <a href="http://restframework.herokuapp.com/">live sandbox</a> is hosted on <a href="http://www.heroku.com/">Heroku</a>.</p>
<p>Various inspiration taken from the <a href="http://rubyonrails.org/">Rails</a>, <a href="https://bitbucket.org/jespern/django-piston">Piston</a>, <a href="https://github.com/toastdriven/django-tastypie">Tastypie</a>, <a href="https://github.com/zacharyvoase/dagny">Dagny</a> and <a href="https://github.com/BertrandBordage/django-viewsets">django-viewsets</a> projects.</p>
<p>Development of REST framework 2.0 was sponsored by <a href="http://lab.dabapps.com">DabApps</a>.</p>
<h2 id="contact">Contact</h2>
<p>For usage questions please see the <a href="https://groups.google.com/forum/?fromgroups#!forum/django-rest-framework">REST framework discussion group</a>.</p>
<p>You can also contact <a href="http://twitter.com/_tomchristie">@_tomchristie</a> directly on twitter.</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>.</a>
</p>
</footer>
<!-- Le javascript
================================================== -->
<!-- Placed at the end of the document so the pages load faster -->
<script src="../../js/jquery-1.8.1-min.js"></script>
<script src="../../js/prettify-1.0.js"></script>
<script src="../../js/bootstrap-2.1.1-min.js"></script>
<script src="../../js/theme.js"></script>
<script>
//$('.side-nav').scrollspy()
var shiftWindow = function() {
scrollBy(0, -50)
};
if (location.hash) shiftWindow();
window.addEventListener("hashchange", shiftWindow);
$('.dropdown-menu').on('click touchstart', function(event) {
event.stopPropagation();
});
// Dynamically force sidenav to no higher than browser window
$('.side-nav').css('max-height', window.innerHeight - 130);
$(function() {
$(window).resize(function() {
$('.side-nav').css('max-height', window.innerHeight - 130);
});
});
</script>
</body>
</html>
\ No newline at end of file
topics/documenting-your-api/index.html
......@@ -62,7 +62,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="../ajax-csrf-cors">
<a class="repo-link btn btn-inverse btn-small " rel="prev" href="../internationalization">
Next <i class="icon-arrow-right icon-white"></i>
</a>
<a class="repo-link btn btn-inverse btn-small " rel="next" href="../../api-guide/settings">
......@@ -189,6 +189,10 @@
</li>
<li >
<a href="../../api-guide/versioning">Versioning</a>
</li>
<li >
<a href="../../api-guide/content-negotiation">Content negotiation</a>
</li>
......@@ -232,6 +236,10 @@
</li>
<li >
<a href="../internationalization">Internationalization</a>
</li>
<li >
<a href="../ajax-csrf-cors">AJAX, CSRF & CORS</a>
</li>
......@@ -260,23 +268,11 @@
</li>
<li >
<a href="../rest-framework-2-announcement">2.0 Announcement</a>
</li>
<li >
<a href="../2.2-announcement">2.2 Announcement</a>
</li>
<li >
<a href="../2.3-announcement">2.3 Announcement</a>
</li>
<li >
<a href="../2.4-announcement">2.4 Announcement</a>
<a href="../3.0-announcement">3.0 Announcement</a>
</li>
<li >
<a href="../3.0-announcement">3.0 Announcement</a>
<a href="../3.1-announcement">3.1 Announcement</a>
</li>
<li >
......@@ -287,10 +283,6 @@
<a href="../release-notes">Release Notes</a>
</li>
<li >
<a href="../credits">Credits</a>
</li>
</ul>
</li>
......
topics/rest-framework-2-announcement/index.html → topics/internationalization/index.html
......@@ -4,11 +4,11 @@
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta charset="utf-8">
<title>2.0 Announcement - Django REST framework</title>
<title>Internationalization - 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/rest-framework-2-announcement/" />
<link rel="canonical" href="http://www.django-rest-framework.org/topics/internationalization/" />
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="description" content="Django, API, REST, 2.0 Announcement">
<meta name="description" content="Django, API, REST, Internationalization">
<meta name="author" content="Tom Christie">
<!-- Le styles -->
......@@ -62,10 +62,10 @@
<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="../2.2-announcement">
<a class="repo-link btn btn-inverse btn-small " rel="prev" href="../ajax-csrf-cors">
Next <i class="icon-arrow-right icon-white"></i>
</a>
<a class="repo-link btn btn-inverse btn-small " rel="next" href="../project-management">
<a class="repo-link btn btn-inverse btn-small " rel="next" href="../documenting-your-api">
<i class="icon-arrow-left icon-white"></i> Previous
</a>
<a class="repo-link btn btn-inverse btn-small" href="#searchModal" data-toggle="modal"><i class="icon-search icon-white"></i> Search</a>
......@@ -189,6 +189,10 @@
</li>
<li >
<a href="../../api-guide/versioning">Versioning</a>
</li>
<li >
<a href="../../api-guide/content-negotiation">Content negotiation</a>
</li>
......@@ -231,6 +235,10 @@
<a href="../documenting-your-api">Documenting your API</a>
</li>
<li class="active" >
<a href=".">Internationalization</a>
</li>
<li >
<a href="../ajax-csrf-cors">AJAX, CSRF & CORS</a>
</li>
......@@ -259,24 +267,12 @@
<a href="../project-management">Project management</a>
</li>
<li class="active" >
<a href=".">2.0 Announcement</a>
</li>
<li >
<a href="../2.2-announcement">2.2 Announcement</a>
</li>
<li >
<a href="../2.3-announcement">2.3 Announcement</a>
</li>
<li >
<a href="../2.4-announcement">2.4 Announcement</a>
<a href="../3.0-announcement">3.0 Announcement</a>
</li>
<li >
<a href="../3.0-announcement">3.0 Announcement</a>
<a href="../3.1-announcement">3.1 Announcement</a>
</li>
<li >
......@@ -287,10 +283,6 @@
<a href="../release-notes">Release Notes</a>
</li>
<li >
<a href="../credits">Credits</a>
</li>
</ul>
</li>
......@@ -353,40 +345,20 @@
<li class="main">
<a href="#django-rest-framework-20">Django REST framework 2.0</a>
<a href="#internationalization">Internationalization</a>
</li>
<li>
<a href="#user-feedback">User feedback</a>
</li>
<li>
<a href="#serialization">Serialization</a>
</li>
<li>
<a href="#generic-views">Generic views</a>
</li>
<li>
<a href="#requests-responses-views">Requests, Responses &amp; Views</a>
<a href="#enabling-internationalized-apis">Enabling internationalized APIs</a>
</li>
<li>
<a href="#api-design">API Design</a>
<a href="#adding-new-translations">Adding new translations</a>
</li>
<li>
<a href="#the-browsable-api">The Browsable API</a>
</li>
<li>
<a href="#documentation">Documentation</a>
</li>
<li>
<a href="#summary">Summary</a>
<a href="#how-the-language-is-determined">How the language is determined</a>
</li>
......@@ -402,57 +374,95 @@
<div id="main-content" class="span9">
<h1 id="django-rest-framework-20">Django REST framework 2.0</h1>
<h1 id="internationalization">Internationalization</h1>
<blockquote>
<p>Most people just make the mistake that it should be simple to design simple things. In reality, the effort required to design something is inversely proportional to the simplicity of the result.</p>
<p>&mdash; <a href="http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven#comment-724">Roy Fielding</a></p>
<p>Supporting internationalization is not optional. It must be a core feature.</p>
<p>&mdash; <a href="http://youtu.be/Wa0VfS2q94Y">Jannis Leidel, speaking at Django Under the Hood, 2015</a>.</p>
</blockquote>
<hr />
<p><strong>Announcement:</strong> REST framework 2 released - Tue 30th Oct 2012</p>
<hr />
<p>REST framework 2 is an almost complete reworking of the original framework, which comprehensively addresses some of the original design issues.</p>
<p>Because the latest version should be considered a re-release, rather than an incremental improvement, we've skipped a version, and called this release Django REST framework 2.0.</p>
<p>This article is intended to give you a flavor of what REST framework 2 is, and why you might want to give it a try.</p>
<h2 id="user-feedback">User feedback</h2>
<p>Before we get cracking, let's start with the hard sell, with a few bits of feedback from some early adopters…</p>
<p>"Django REST framework 2 is beautiful. Some of the API design is worthy of @kennethreitz." - <a href="https://twitter.com/kobutsu/status/261689665952833536">Kit La Touche</a></p>
<p>"Since it's pretty much just Django, controlling things like URLs has been a breeze... I think [REST framework 2] has definitely got the right approach here; even simple things like being able to override a function called post to do custom work during rather than having to intimately know what happens during a post make a huge difference to your productivity." - <a href="https://groups.google.com/d/msg/django-rest-framework/heRGHzG6BWQ/ooVURgpwVC0J">Ian Strachan</a></p>
<p>"I switched to the 2.0 branch and I don't regret it - fully refactored my code in another &half; day and it's <em>much</em> more to my tastes" - <a href="https://groups.google.com/d/msg/django-rest-framework/flsXbvYqRoY/9lSyntOf5cUJ">Bruno Desthuilliers</a></p>
<p>Sounds good, right? Let's get into some details...</p>
<h2 id="serialization">Serialization</h2>
<p>REST framework 2 includes a totally re-worked serialization engine, that was initially intended as a replacement for Django's existing inflexible fixture serialization, and which meets the following design goals:</p>
<p>REST framework ships with translatable error messages. You can make these appear in your language enabling <a href="https://docs.djangoproject.com/en/1.7/topics/i18n/translation">Django's standard translation mechanisms</a>.</p>
<p>Doing so will allow you to:</p>
<ul>
<li>Select a language other than English as the default, using the standard <code>LANGUAGE_CODE</code> Django setting.</li>
<li>Allow clients to choose a language themselves, using the <code>LocaleMiddleware</code> included with Django. A typical usage for API clients would be to include an <code>Accept-Language</code> request header.</li>
</ul>
<h2 id="enabling-internationalized-apis">Enabling internationalized APIs</h2>
<p>You can change the default language by using the standard Django <code>LANGUAGE_CODE</code> setting:</p>
<pre><code>LANGUAGE_CODE = "es-es"
</code></pre>
<p>You can turn on per-request language requests by adding <code>LocalMiddleware</code> to your <code>MIDDLEWARE_CLASSES</code> setting:</p>
<pre><code>MIDDLEWARE_CLASSES = [
...
'django.middleware.locale.LocaleMiddleware'
]
</code></pre>
<p>When per-request internationalization is enabled, client requests will respect the <code>Accept-Language</code> header where possible. For example, let's make a request for an unsupported media type:</p>
<p><strong>Request</strong></p>
<pre><code>GET /api/users HTTP/1.1
Accept: application/xml
Accept-Language: es-es
Host: example.org
</code></pre>
<p><strong>Response</strong></p>
<pre><code>HTTP/1.0 406 NOT ACCEPTABLE
{"detail": "No se ha podido satisfacer la solicitud de cabecera de Accept."}
</code></pre>
<p>REST framework includes these built-in translations both for standard exception cases, and for serializer validation errors.</p>
<p>Note that the translations only apply to the error strings themselves. The format of error messages, and the keys of field names will remain the same. An example <code>400 Bad Request</code> response body might look like this:</p>
<pre><code>{"detail": {"username": ["Esse campo deve ser unico."]}}
</code></pre>
<p>If you want to use different string for parts of the response such as <code>detail</code> and <code>non_field_errors</code> then you can modify this behavior by using a <a href="../../api-guide/exceptions#custom-exception-handling">custom exception handler</a>.</p>
<h4 id="specifying-the-set-of-supported-languages">Specifying the set of supported languages.</h4>
<p>By default all available languages will be supported.</p>
<p>If you only wish to support a subset of the available languages, use Django's standard <code>LANGUAGES</code> setting:</p>
<pre><code>LANGUAGES = [
('de', _('German')),
('en', _('English')),
]
</code></pre>
<h2 id="adding-new-translations">Adding new translations</h2>
<p>REST framework translations are managed online using <a href="https://www.transifex.com/projects/p/django-rest-framework/">Transifex</a>. You can use the Transifex service to add new translation languages. The maintenance team will then ensure that these translation strings are included in the REST framework package.</p>
<p>Sometimes you may need to add translation strings to your project locally. You may need to do this if:</p>
<ul>
<li>A declarative serialization API, that mirrors Django's <code>Forms</code>/<code>ModelForms</code> API.</li>
<li>Structural concerns are decoupled from encoding concerns.</li>
<li>Able to support rendering and parsing to many formats, including both machine-readable representations and HTML forms.</li>
<li>Validation that can be mapped to obvious and comprehensive error responses.</li>
<li>Serializers that support both nested, flat, and partially-nested representations.</li>
<li>Relationships that can be expressed as primary keys, hyperlinks, slug fields, and other custom representations.</li>
<li>You want to use REST Framework in a language which has not been translated yet on Transifex.</li>
<li>Your project includes custom error messages, which are not part of REST framework's default translation strings.</li>
</ul>
<p>Mapping between the internal state of the system and external representations of that state is the core concern of building Web APIs. Designing serializers that allow the developer to do so in a flexible and obvious way is a deceptively difficult design task, and with the new serialization API we think we've pretty much nailed it.</p>
<h2 id="generic-views">Generic views</h2>
<p>When REST framework was initially released at the start of 2011, the current Django release was version 1.2. REST framework included a backport of Django 1.3's upcoming <code>View</code> class, but it didn't take full advantage of the generic view implementations.</p>
<p>With the new release the generic views in REST framework now tie in with Django's generic views. The end result is that framework is clean, lightweight and easy to use.</p>
<h2 id="requests-responses-views">Requests, Responses &amp; Views</h2>
<p>REST framework 2 includes <code>Request</code> and <code>Response</code> classes, than are used in place of Django's existing <code>HttpRequest</code> and <code>HttpResponse</code> classes. Doing so allows logic such as parsing the incoming request or rendering the outgoing response to be supported transparently by the framework.</p>
<p>The <code>Request</code>/<code>Response</code> approach leads to a much cleaner API, less logic in the view itself, and a simple, obvious request-response cycle.</p>
<p>REST framework 2 also allows you to work with both function-based and class-based views. For simple API views all you need is a single <code>@api_view</code> decorator, and you're good to go.</p>
<h2 id="api-design">API Design</h2>
<p>Pretty much every aspect of REST framework has been reworked, with the aim of ironing out some of the design flaws of the previous versions. Each of the components of REST framework are cleanly decoupled, and can be used independently of each-other, and there are no monolithic resource classes, overcomplicated mixin combinations, or opinionated serialization or URL routing decisions.</p>
<h2 id="the-browsable-api">The Browsable API</h2>
<p>Django REST framework's most unique feature is the way it is able to serve up both machine-readable representations, and a fully browsable HTML representation to the same endpoints.</p>
<p>Browsable Web APIs are easier to work with, visualize and debug, and generally makes it easier and more frictionless to inspect and work with.</p>
<p>With REST framework 2, the browsable API gets a snazzy new bootstrap-based theme that looks great and is even nicer to work with.</p>
<p>There are also some functionality improvements - actions such as as <code>POST</code> and <code>DELETE</code> will only display if the user has the appropriate permissions.</p>
<p><img alt="Browsable API" src="../../../img/quickstart.png" /></p>
<p><strong>Image above</strong>: An example of the browsable API in REST framework 2</p>
<h2 id="documentation">Documentation</h2>
<p>As you can see the documentation for REST framework has been radically improved. It gets a completely new style, using markdown for the documentation source, and a bootstrap-based theme for the styling.</p>
<p>We're really pleased with how the docs style looks - it's simple and clean, is easy to navigate around, and we think it reads great.</p>
<h2 id="summary">Summary</h2>
<p>In short, we've engineered the hell outta this thing, and we're incredibly proud of the result.</p>
<p>If you're interested please take a browse around the documentation. <a href="../../tutorial/1-serialization">The tutorial</a> is a great place to get started.</p>
<p>There's also a <a href="http://restframework.herokuapp.com/">live sandbox version of the tutorial API</a> available for testing.</p>
<h4 id="translating-a-new-language-locally">Translating a new language locally</h4>
<p>This guide assumes you are already familiar with how to translate a Django app. If you're not, start by reading <a href="https://docs.djangoproject.com/en/1.7/topics/i18n/translation">Django's translation docs</a>.</p>
<p>If you're translating a new language you'll need to translate the existing REST framework error messages:</p>
<ol>
<li>
<p>Make a new folder where you want to store the internationalization resources. Add this path to your <a href="https://docs.djangoproject.com/en/1.7/ref/settings/#std:setting-LOCALE_PATHS"><code>LOCALE_PATHS</code></a> setting.</p>
</li>
<li>
<p>Now create a subfolder for the language you want to translate. The folder should be named using <a href="https://docs.djangoproject.com/en/1.7/topics/i18n/#term-locale-name">locale name</a> notation. For example: <code>de</code>, <code>pt_BR</code>, <code>es_AR</code>.</p>
</li>
<li>
<p>Now copy the <a href="https://raw.githubusercontent.com/tomchristie/django-rest-framework/master/rest_framework/locale/en_US/LC_MESSAGES/django.po">base translations file</a> from the REST framework source code into your translations folder.</p>
</li>
<li>
<p>Edit the <code>django.po</code> file you've just copied, translating all the error messages.</p>
</li>
<li>
<p>Run <code>manage.py compilemessages -l pt_BR</code> to make the translations
available for Django to use. You should see a message like <code>processing file django.po in &lt;...&gt;/locale/pt_BR/LC_MESSAGES</code>.</p>
</li>
<li>
<p>Restart your development server to see the changes take effect.</p>
</li>
</ol>
<p>If you're only translating custom error messages that exist inside your project codebase you don't need to copy the REST framework source <code>django.po</code> file into a <code>LOCALE_PATHS</code> folder, and can instead simply run Django's standard <code>makemessages</code> process.</p>
<h2 id="how-the-language-is-determined">How the language is determined</h2>
<p>If you want to allow per-request language preferences you'll need to include <code>django.middleware.locale.LocaleMiddleware</code> in your <code>MIDDLEWARE_CLASSES</code> setting.</p>
<p>You can find more information on how the language preference is determined in the <a href="https://docs.djangoproject.com/en/1.7/topics/i18n/translation/#how-django-discovers-language-preference">Django documentation</a>. For reference, the method is:</p>
<ol>
<li>First, it looks for the language prefix in the requested URL.</li>
<li>Failing that, it looks for the <code>LANGUAGE_SESSION_KEY</code> key in the current user’s session.</li>
<li>Failing that, it looks for a cookie.</li>
<li>Failing that, it looks at the <code>Accept-Language</code> HTTP header.</li>
<li>Failing that, it uses the global <code>LANGUAGE_CODE</code> setting.</li>
</ol>
<p>For API clients the most appropriate of these will typically be to use the <code>Accept-Language</code> header; Sessions and cookies will not be available unless using session authentication, and generally better practice to prefer an <code>Accept-Language</code> header for API clients rather than using language URL prefixes.</p>
</div>
<!--/span-->
......
topics/kickstarter-announcement/index.html
......@@ -65,7 +65,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.0-announcement">
<a class="repo-link btn btn-inverse btn-small " rel="next" href="../3.1-announcement">
<i class="icon-arrow-left icon-white"></i> Previous
</a>
<a class="repo-link btn btn-inverse btn-small" href="#searchModal" data-toggle="modal"><i class="icon-search icon-white"></i> Search</a>
......@@ -189,6 +189,10 @@
</li>
<li >
<a href="../../api-guide/versioning">Versioning</a>
</li>
<li >
<a href="../../api-guide/content-negotiation">Content negotiation</a>
</li>
......@@ -232,6 +236,10 @@
</li>
<li >
<a href="../internationalization">Internationalization</a>
</li>
<li >
<a href="../ajax-csrf-cors">AJAX, CSRF & CORS</a>
</li>
......@@ -260,23 +268,11 @@
</li>
<li >
<a href="../rest-framework-2-announcement">2.0 Announcement</a>
</li>
<li >
<a href="../2.2-announcement">2.2 Announcement</a>
</li>
<li >
<a href="../2.3-announcement">2.3 Announcement</a>
</li>
<li >
<a href="../2.4-announcement">2.4 Announcement</a>
<a href="../3.0-announcement">3.0 Announcement</a>
</li>
<li >
<a href="../3.0-announcement">3.0 Announcement</a>
<a href="../3.1-announcement">3.1 Announcement</a>
</li>
<li class="active" >
......@@ -287,10 +283,6 @@
<a href="../release-notes">Release Notes</a>
</li>
<li >
<a href="../credits">Credits</a>
</li>
</ul>
</li>
......
topics/project-management/index.html
......@@ -62,7 +62,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="../rest-framework-2-announcement">
<a class="repo-link btn btn-inverse btn-small " rel="prev" href="../3.0-announcement">
Next <i class="icon-arrow-right icon-white"></i>
</a>
<a class="repo-link btn btn-inverse btn-small " rel="next" href="../contributing">
......@@ -189,6 +189,10 @@
</li>
<li >
<a href="../../api-guide/versioning">Versioning</a>
</li>
<li >
<a href="../../api-guide/content-negotiation">Content negotiation</a>
</li>
......@@ -232,6 +236,10 @@
</li>
<li >
<a href="../internationalization">Internationalization</a>
</li>
<li >
<a href="../ajax-csrf-cors">AJAX, CSRF & CORS</a>
</li>
......@@ -260,23 +268,11 @@
</li>
<li >
<a href="../rest-framework-2-announcement">2.0 Announcement</a>
</li>
<li >
<a href="../2.2-announcement">2.2 Announcement</a>
</li>
<li >
<a href="../2.3-announcement">2.3 Announcement</a>
</li>
<li >
<a href="../2.4-announcement">2.4 Announcement</a>
<a href="../3.0-announcement">3.0 Announcement</a>
</li>
<li >
<a href="../3.0-announcement">3.0 Announcement</a>
<a href="../3.1-announcement">3.1 Announcement</a>
</li>
<li >
......@@ -287,10 +283,6 @@
<a href="../release-notes">Release Notes</a>
</li>
<li >
<a href="../credits">Credits</a>
</li>
</ul>
</li>
......@@ -366,6 +358,14 @@
</li>
<li>
<a href="#translations">Translations</a>
</li>
<li>
<a href="#project-requirements">Project requirements</a>
</li>
<li>
<a href="#project-ownership">Project ownership</a>
</li>
......@@ -438,10 +438,11 @@ To modify this process for future maintenance cycles make a pull request to the
<h4 id="responsibilities-of-team-members">Responsibilities of team members</h4>
<p>Team members have the following responsibilities.</p>
<ul>
<li>Add triage labels and milestones to tickets.</li>
<li>Close invalid or resolved tickets.</li>
<li>Add triage labels and milestones to tickets.</li>
<li>Merge finalized pull requests.</li>
<li>Build and deploy the documentation, using <code>mkdocs gh-deploy</code>.</li>
<li>Build and update the included translation packs.</li>
</ul>
<p>Further notes for maintainers:</p>
<ul>
......@@ -482,6 +483,48 @@ To modify this process for future releases make a pull request to the [project m
</code></pre>
<p>When pushing the release to PyPI ensure that your environment has been installed from our development <code>requirement.txt</code>, so that documentation and PyPI installs are consistently being built against a pinned set of packages.</p>
<hr />
<h2 id="translations">Translations</h2>
<p>The maintenance team are responsible for managing the translation packs include in REST framework. Translating the source strings into multiple languages is managed through the <a href="https://www.transifex.com/projects/p/django-rest-framework/">transifex service</a>.</p>
<h3 id="managing-transifex">Managing Transifex</h3>
<p>The <a href="https://pypi.python.org/pypi/transifex-client">official Transifex client</a> is used to upload and download translations to Transifex. The client is installed using pip:</p>
<pre><code>pip install transifex-client
</code></pre>
<p>To use it you'll need a login to Transifex which has a password, and you'll need to have administrative access to the Transifex project. You'll need to create a <code>~/.transifexrc</code> file which contains your credentials.</p>
<pre><code>[https://www.transifex.com]
username = ***
token = ***
password = ***
hostname = https://www.transifex.com
</code></pre>
<h3 id="upload-new-source-files">Upload new source files</h3>
<p>When any user visible strings are changed, they should be uploaded to Transifex so that the translators can start to translate them. To do this, just run:</p>
<pre><code># 1. Update the source django.po file, which is the US English version.
cd rest_framework
django-admin.py makemessages -l en_US
# 2. Push the source django.po file to Transifex.
cd ..
tx push -s
</code></pre>
<p>When pushing source files, Transifex will update the source strings of a resource to match those from the new source file.</p>
<p>Here's how differences between the old and new source files will be handled:</p>
<ul>
<li>New strings will be added.</li>
<li>Modified strings will be added as well.</li>
<li>Strings which do not exist in the new source file will be removed from the database, along with their translations. If that source strings gets re-added later then <a href="http://docs.transifex.com/guides/tm#let-tm-automatically-populate-translations">Transifex Translation Memory</a> will automatically include the translation string.</li>
</ul>
<h3 id="download-translations">Download translations</h3>
<p>When a translator has finished translating their work needs to be downloaded from Transifex into the REST framework repository. To do this, run:</p>
<pre><code># 3. Pull the translated django.po files from Transifex.
tx pull -a
cd rest_framework
# 4. Compile the binary .mo files for all supported languages.
django-admin.py compilemessages
</code></pre>
<hr />
<h2 id="project-requirements">Project requirements</h2>
<p>All our test requirements are pinned to exact versions, in order to ensure that our test runs are reproducible. We maintain the requirements in the <code>requirements</code> directory. The requirements files are referenced from the <code>tox.ini</code> configuration file, ensuring we have a single source of truth for package versions used in testing.</p>
<p>Package upgrades should generally be treated as isolated pull requests. You can check if there are any packages available at a newer version, by using the <code>pip list --outdated</code>.</p>
<hr />
<h2 id="project-ownership">Project ownership</h2>
<p>The PyPI package is owned by <code>@tomchristie</code>. As a backup <code>@j4mie</code> also has ownership of the package.</p>
<p>If <code>@tomchristie</code> ceases to participate in the project then <code>@j4mie</code> has responsibility for handing over ownership duties.</p>
......
topics/release-notes/index.html
......@@ -62,7 +62,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="../credits">
<a class="repo-link btn btn-inverse btn-small disabled" rel="prev" >
Next <i class="icon-arrow-right icon-white"></i>
</a>
<a class="repo-link btn btn-inverse btn-small " rel="next" href="../kickstarter-announcement">
......@@ -189,6 +189,10 @@
</li>
<li >
<a href="../../api-guide/versioning">Versioning</a>
</li>
<li >
<a href="../../api-guide/content-negotiation">Content negotiation</a>
</li>
......@@ -232,6 +236,10 @@
</li>
<li >
<a href="../internationalization">Internationalization</a>
</li>
<li >
<a href="../ajax-csrf-cors">AJAX, CSRF & CORS</a>
</li>
......@@ -260,23 +268,11 @@
</li>
<li >
<a href="../rest-framework-2-announcement">2.0 Announcement</a>
</li>
<li >
<a href="../2.2-announcement">2.2 Announcement</a>
</li>
<li >
<a href="../2.3-announcement">2.3 Announcement</a>
</li>
<li >
<a href="../2.4-announcement">2.4 Announcement</a>
<a href="../3.0-announcement">3.0 Announcement</a>
</li>
<li >
<a href="../3.0-announcement">3.0 Announcement</a>
<a href="../3.1-announcement">3.1 Announcement</a>
</li>
<li >
......@@ -287,10 +283,6 @@
<a href=".">Release Notes</a>
</li>
<li >
<a href="../credits">Credits</a>
</li>
</ul>
</li>
......@@ -373,26 +365,6 @@
<a href="#30x-series">3.0.x series</a>
</li>
<li>
<a href="#24x-series">2.4.x series</a>
</li>
<li>
<a href="#23x-series">2.3.x series</a>
</li>
<li>
<a href="#22x-series">2.2.x series</a>
</li>
<li>
<a href="#21x-series">2.1.x series</a>
</li>
<li>
<a href="#20x-series">2.0.x series</a>
</li>
......@@ -439,6 +411,9 @@
</code></pre>
<hr />
<h2 id="30x-series">3.0.x series</h2>
<h3 id="310">3.1.0</h3>
<p><strong>Date</strong>: [5th March 2015][3.1.0-milestone].</p>
<p>For full details see the <a href="../3.1-announcement">3.1 release announcement</a>.</p>
<h3 id="305">3.0.5</h3>
<p><strong>Date</strong>: <a href="https://github.com/tomchristie/django-rest-framework/issues?q=milestone%3A%223.0.5+Release%22">10th February 2015</a>.</p>
<ul>
......@@ -526,509 +501,7 @@
<p><strong>Date</strong>: 1st December 2014</p>
<p>For full details see the <a href="../3.0-announcement">3.0 release announcement</a>.</p>
<hr />
<h2 id="24x-series">2.4.x series</h2>
<h3 id="244">2.4.4</h3>
<p><strong>Date</strong>: <a href="https://github.com/tomchristie/django-rest-framework/issues?q=milestone%3A%222.4.4+Release%22+">3rd November 2014</a>.</p>
<ul>
<li><strong>Security fix</strong>: Escape URLs when replacing <code>format=</code> query parameter, as used in dropdown on <code>GET</code> button in browsable API to allow explicit selection of JSON vs HTML output.</li>
<li>Maintain ordering of URLs in API root view for <code>DefaultRouter</code>.</li>
<li>Fix <code>follow=True</code> in <code>APIRequestFactory</code></li>
<li>Resolve issue with invalid <code>read_only=True</code>, <code>required=True</code> fields being automatically generated by <code>ModelSerializer</code> in some cases.</li>
<li>Resolve issue with <code>OPTIONS</code> requests returning incorrect information for views using <code>get_serializer_class</code> to dynamically determine serializer based on request method. </li>
</ul>
<h3 id="243">2.4.3</h3>
<p><strong>Date</strong>: <a href="https://github.com/tomchristie/django-rest-framework/issues?q=milestone%3A%222.4.3+Release%22+">19th September 2014</a>.</p>
<ul>
<li>Support translatable view docstrings being displayed in the browsable API.</li>
<li>Support <a href="http://tools.ietf.org/html/rfc6266#section-4.3">encoded <code>filename*</code></a> in raw file uploads with <code>FileUploadParser</code>.</li>
<li>Allow routers to support viewsets that don't include any list routes or that don't include any detail routes.</li>
<li>Don't render an empty login control in browsable API if <code>login</code> view is not included.</li>
<li>CSRF exemption performed in <code>.as_view()</code> to prevent accidental omission if overriding <code>.dispatch()</code>.</li>
<li>Login on browsable API now displays validation errors.</li>
<li>Bugfix: Fix migration in <code>authtoken</code> application.</li>
<li>Bugfix: Allow selection of integer keys in nested choices.</li>
<li>Bugfix: Return <code>None</code> instead of <code>'None'</code> in <code>CharField</code> with <code>allow_none=True</code>.</li>
<li>Bugfix: Ensure custom model fields map to equivelent serializer fields more reliably.</li>
<li>Bugfix: <code>DjangoFilterBackend</code> no longer quietly changes queryset ordering.</li>
</ul>
<h3 id="242">2.4.2</h3>
<p><strong>Date</strong>: <a href="https://github.com/tomchristie/django-rest-framework/issues?q=milestone%3A%222.4.2+Release%22+">3rd September 2014</a>.</p>
<ul>
<li>Bugfix: Fix broken pagination for 2.4.x series.</li>
</ul>
<h3 id="241">2.4.1</h3>
<p><strong>Date</strong>: <a href="https://github.com/tomchristie/django-rest-framework/issues?q=milestone%3A%222.4.1+Release%22+">1st September 2014</a>.</p>
<ul>
<li>Bugfix: Fix broken login template for browsable API.</li>
</ul>
<h3 id="240">2.4.0</h3>
<p><strong>Date</strong>: <a href="https://github.com/tomchristie/django-rest-framework/issues?q=milestone%3A%222.4.0+Release%22+">29th August 2014</a>.</p>
<p><strong>Django version requirements</strong>: The lowest supported version of Django is now 1.4.2.</p>
<p><strong>South version requirements</strong>: This note applies to any users using the optional <code>authtoken</code> application, which includes an associated database migration. You must now <em>either</em> upgrade your <code>south</code> package to version 1.0, <em>or</em> instead use the built-in migration support available with Django 1.7.</p>
<ul>
<li>Added compatibility with Django 1.7's database migration support.</li>
<li>New test runner, using <code>py.test</code>.</li>
<li>Deprecated <code>.model</code> view attribute in favor of explicit <code>.queryset</code> and <code>.serializer_class</code> attributes. The <code>DEFAULT_MODEL_SERIALIZER_CLASS</code> setting is also deprecated.</li>
<li><code>@detail_route</code> and <code>@list_route</code> decorators replace <code>@action</code> and <code>@link</code>.</li>
<li>Support customizable view name and description functions, using the <code>VIEW_NAME_FUNCTION</code> and <code>VIEW_DESCRIPTION_FUNCTION</code> settings.</li>
<li>Added <code>NUM_PROXIES</code> setting for smarter client IP identification.</li>
<li>Added <code>MAX_PAGINATE_BY</code> setting and <code>max_paginate_by</code> generic view attribute.</li>
<li>Added <code>Retry-After</code> header to throttled responses, as per <a href="http://tools.ietf.org/html/rfc6585">RFC 6585</a>. This should now be used in preference to the custom <code>X-Trottle-Wait-Seconds</code> header which will be fully deprecated in 3.0.</li>
<li>Added <code>cache</code> attribute to throttles to allow overriding of default cache.</li>
<li>Added <code>lookup_value_regex</code> attribute to routers, to allow the URL argument matching to be constrainted by the user.</li>
<li>Added <code>allow_none</code> option to <code>CharField</code>.</li>
<li>Support Django's standard <code>status_code</code> class attribute on responses.</li>
<li>More intuitive behavior on the test client, as <code>client.logout()</code> now also removes any credentials that have been set.</li>
<li>Bugfix: <code>?page_size=0</code> query parameter now falls back to default page size for view, instead of always turning pagination off.</li>
<li>Bugfix: Always uppercase <code>X-Http-Method-Override</code> methods.</li>
<li>Bugfix: Copy <code>filter_backends</code> list before returning it, in order to prevent view code from mutating the class attribute itself.</li>
<li>Bugfix: Set the <code>.action</code> attribute on viewsets when introspected by <code>OPTIONS</code> for testing permissions on the view.</li>
<li>Bugfix: Ensure <code>ValueError</code> raised during deserialization results in a error list rather than a single error. This is now consistent with other validation errors.</li>
<li>Bugfix: Fix <code>cache_format</code> typo on throttle classes, was <code>"throtte_%(scope)s_%(ident)s"</code>. Note that this will invalidate existing throttle caches.</li>
</ul>
<hr />
<h2 id="23x-series">2.3.x series</h2>
<h3 id="2314">2.3.14</h3>
<p><strong>Date</strong>: 12th June 2014</p>
<ul>
<li><strong>Security fix</strong>: Escape request path when it is include as part of the login and logout links in the browsable API.</li>
<li><code>help_text</code> and <code>verbose_name</code> automatically set for related fields on <code>ModelSerializer</code>.</li>
<li>Fix nested serializers linked through a backward foreign key relation.</li>
<li>Fix bad links for the <code>BrowsableAPIRenderer</code> with <code>YAMLRenderer</code>.</li>
<li>Add <code>UnicodeYAMLRenderer</code> that extends <code>YAMLRenderer</code> with unicode.</li>
<li>Fix <code>parse_header</code> argument convertion.</li>
<li>Fix mediatype detection under Python 3.</li>
<li>Web browsable API now offers blank option on dropdown when the field is not required.</li>
<li><code>APIException</code> representation improved for logging purposes.</li>
<li>Allow source="*" within nested serializers.</li>
<li>Better support for custom oauth2 provider backends.</li>
<li>Fix field validation if it's optional and has no value.</li>
<li>Add <code>SEARCH_PARAM</code> and <code>ORDERING_PARAM</code>.</li>
<li>Fix <code>APIRequestFactory</code> to support arguments within the url string for GET.</li>
<li>Allow three transport modes for access tokens when accessing a protected resource.</li>
<li>Fix <code>QueryDict</code> encoding on request objects.</li>
<li>Ensure throttle keys do not contain spaces, as those are invalid if using <code>memcached</code>.</li>
<li>Support <code>blank_display_value</code> on <code>ChoiceField</code>.</li>
</ul>
<h3 id="2313">2.3.13</h3>
<p><strong>Date</strong>: 6th March 2014</p>
<ul>
<li>Django 1.7 Support.</li>
<li>Fix <code>default</code> argument when used with serializer relation fields.</li>
<li>Display the media type of the content that is being displayed in the browsable API, rather than 'text/html'.</li>
<li>Bugfix for <code>urlize</code> template failure when URL regex is matched, but value does not <code>urlparse</code>.</li>
<li>Use <code>urandom</code> for token generation.</li>
<li>Only use <code>Vary: Accept</code> when more than one renderer exists.</li>
</ul>
<h3 id="2312">2.3.12</h3>
<p><strong>Date</strong>: 15th January 2014</p>
<ul>
<li><strong>Security fix</strong>: <code>OrderingField</code> now only allows ordering on readable serializer fields, or on fields explicitly specified using <code>ordering_fields</code>. This prevents users being able to order by fields that are not visible in the API, and exploiting the ordering of sensitive data such as password hashes.</li>
<li>Bugfix: <code>write_only = True</code> fields now display in the browsable API.</li>
</ul>
<h3 id="2311">2.3.11</h3>
<p><strong>Date</strong>: 14th January 2014</p>
<ul>
<li>Added <code>write_only</code> serializer field argument.</li>
<li>Added <code>write_only_fields</code> option to <code>ModelSerializer</code> classes.</li>
<li>JSON renderer now deals with objects that implement a dict-like interface.</li>
<li>Fix compatiblity with newer versions of <code>django-oauth-plus</code>.</li>
<li>Bugfix: Refine behavior that calls model manager <code>all()</code> across nested serializer relationships, preventing erronous behavior with some non-ORM objects, and preventing unnecessary queryset re-evaluations.</li>
<li>Bugfix: Allow defaults on BooleanFields to be properly honored when values are not supplied.</li>
<li>Bugfix: Prevent double-escaping of non-latin1 URL query params when appending <code>format=json</code> params.</li>
</ul>
<h3 id="2310">2.3.10</h3>
<p><strong>Date</strong>: 6th December 2013</p>
<ul>
<li>Add in choices information for ChoiceFields in response to <code>OPTIONS</code> requests.</li>
<li>Added <code>pre_delete()</code> and <code>post_delete()</code> method hooks.</li>
<li>Added status code category helper functions.</li>
<li>Bugfix: Partial updates which erronously set a related field to <code>None</code> now correctly fail validation instead of raising an exception.</li>
<li>Bugfix: Responses without any content no longer include an HTTP <code>'Content-Type'</code> header.</li>
<li>Bugfix: Correctly handle validation errors in PUT-as-create case, responding with 400.</li>
</ul>
<h3 id="239">2.3.9</h3>
<p><strong>Date</strong>: 15th November 2013</p>
<ul>
<li>Fix Django 1.6 exception API compatibility issue caused by <code>ValidationError</code>.</li>
<li>Include errors in HTML forms in browsable API.</li>
<li>Added JSON renderer support for numpy scalars.</li>
<li>Added <code>transform_&lt;fieldname&gt;</code> hooks on serializers for easily modifying field output.</li>
<li>Added <code>get_context</code> hook in <code>BrowsableAPIRenderer</code>.</li>
<li>Allow serializers to be passed <code>files</code> but no <code>data</code>.</li>
<li><code>HTMLFormRenderer</code> now renders serializers directly to HTML without needing to create an intermediate form object.</li>
<li>Added <code>get_filter_backends</code> hook.</li>
<li>Added queryset aggregates to allowed fields in <code>OrderingFilter</code>.</li>
<li>Bugfix: Fix decimal suppoprt with <code>YAMLRenderer</code>.</li>
<li>Bugfix: Fix submission of unicode in browsable API through raw data form.</li>
</ul>
<h3 id="238">2.3.8</h3>
<p><strong>Date</strong>: 11th September 2013</p>
<ul>
<li>Added <code>DjangoObjectPermissions</code>, and <code>DjangoObjectPermissionsFilter</code>.</li>
<li>Support customizable exception handling, using the <code>EXCEPTION_HANDLER</code> setting.</li>
<li>Support customizable view name and description functions, using the <code>VIEW_NAME_FUNCTION</code> and <code>VIEW_DESCRIPTION_FUNCTION</code> settings.</li>
<li>Added <code>MAX_PAGINATE_BY</code> setting and <code>max_paginate_by</code> generic view attribute.</li>
<li>Added <code>cache</code> attribute to throttles to allow overriding of default cache.</li>
<li>'Raw data' tab in browsable API now contains pre-populated data.</li>
<li>'Raw data' and 'HTML form' tab preference in browsable API now saved between page views.</li>
<li>Bugfix: <code>required=True</code> argument fixed for boolean serializer fields.</li>
<li>Bugfix: <code>client.force_authenticate(None)</code> should also clear session info if it exists.</li>
<li>Bugfix: Client sending empty string instead of file now clears <code>FileField</code>.</li>
<li>Bugfix: Empty values on ChoiceFields with <code>required=False</code> now consistently return <code>None</code>.</li>
<li>Bugfix: Clients setting <code>page_size=0</code> now simply returns the default page size, instead of disabling pagination. [*]</li>
</ul>
<hr />
<p>[*] Note that the change in <code>page_size=0</code> behaviour fixes what is considered to be a bug in how clients can effect the pagination size. However if you were relying on this behavior you will need to add the following mixin to your list views in order to preserve the existing behavior.</p>
<pre><code>class DisablePaginationMixin(object):
def get_paginate_by(self, queryset=None):
if self.request.QUERY_PARAMS[self.paginate_by_param] == '0':
return None
return super(DisablePaginationMixin, self).get_paginate_by(queryset)
</code></pre>
<hr />
<h3 id="237">2.3.7</h3>
<p><strong>Date</strong>: 16th August 2013</p>
<ul>
<li>Added <code>APITestClient</code>, <code>APIRequestFactory</code> and <code>APITestCase</code> etc...</li>
<li>Refactor <code>SessionAuthentication</code> to allow esier override for CSRF exemption.</li>
<li>Remove 'Hold down "Control" message from help_text' widget messaging when not appropriate.</li>
<li>Added admin configuration for auth tokens.</li>
<li>Bugfix: <code>AnonRateThrottle</code> fixed to not throttle authenticated users.</li>
<li>Bugfix: Don't set <code>X-Throttle-Wait-Seconds</code> when throttle does not have <code>wait</code> value.</li>
<li>Bugfix: Fixed <code>PATCH</code> button title in browsable API.</li>
<li>Bugfix: Fix issue with OAuth2 provider naive datetimes.</li>
</ul>
<h3 id="236">2.3.6</h3>
<p><strong>Date</strong>: 27th June 2013</p>
<ul>
<li>Added <code>trailing_slash</code> option to routers.</li>
<li>Include support for <code>HttpStreamingResponse</code>.</li>
<li>Support wider range of default serializer validation when used with custom model fields.</li>
<li>UTF-8 Support for browsable API descriptions.</li>
<li>OAuth2 provider uses timezone aware datetimes when supported.</li>
<li>Bugfix: Return error correctly when OAuth non-existent consumer occurs.</li>
<li>Bugfix: Allow <code>FileUploadParser</code> to correctly filename if provided as URL kwarg.</li>
<li>Bugfix: Fix <code>ScopedRateThrottle</code>.</li>
</ul>
<h3 id="235">2.3.5</h3>
<p><strong>Date</strong>: 3rd June 2013</p>
<ul>
<li>Added <code>get_url</code> hook to <code>HyperlinkedIdentityField</code>.</li>
<li>Serializer field <code>default</code> argument may be a callable.</li>
<li><code>@action</code> decorator now accepts a <code>methods</code> argument.</li>
<li>Bugfix: <code>request.user</code> should be still be accessible in renderer context if authentication fails.</li>
<li>Bugfix: The <code>lookup_field</code> option on <code>HyperlinkedIdentityField</code> should apply by default to the url field on the serializer.</li>
<li>Bugfix: <code>HyperlinkedIdentityField</code> should continue to support <code>pk_url_kwarg</code>, <code>slug_url_kwarg</code>, <code>slug_field</code>, in a pending deprecation state.</li>
<li>Bugfix: Ensure we always return 404 instead of 500 if a lookup field cannot be converted to the correct lookup type. (Eg non-numeric <code>AutoInteger</code> pk lookup)</li>
</ul>
<h3 id="234">2.3.4</h3>
<p><strong>Date</strong>: 24th May 2013</p>
<ul>
<li>Serializer fields now support <code>label</code> and <code>help_text</code>.</li>
<li>Added <code>UnicodeJSONRenderer</code>.</li>
<li><code>OPTIONS</code> requests now return metadata about fields for <code>POST</code> and <code>PUT</code> requests.</li>
<li>Bugfix: <code>charset</code> now properly included in <code>Content-Type</code> of responses.</li>
<li>Bugfix: Blank choice now added in browsable API on nullable relationships.</li>
<li>Bugfix: Many to many relationships with <code>through</code> tables are now read-only.</li>
<li>Bugfix: Serializer fields now respect model field args such as <code>max_length</code>.</li>
<li>Bugfix: SlugField now performs slug validation.</li>
<li>Bugfix: Lazy-translatable strings now properly serialized.</li>
<li>Bugfix: Browsable API now supports bootswatch styles properly.</li>
<li>Bugfix: HyperlinkedIdentityField now uses <code>lookup_field</code> kwarg.</li>
</ul>
<p><strong>Note</strong>: Responses now correctly include an appropriate charset on the <code>Content-Type</code> header. For example: <code>application/json; charset=utf-8</code>. If you have tests that check the content type of responses, you may need to update these accordingly.</p>
<h3 id="233">2.3.3</h3>
<p><strong>Date</strong>: 16th May 2013</p>
<ul>
<li>Added SearchFilter</li>
<li>Added OrderingFilter</li>
<li>Added GenericViewSet</li>
<li>Bugfix: Multiple <code>@action</code> and <code>@link</code> methods now allowed on viewsets.</li>
<li>Bugfix: Fix API Root view issue with DjangoModelPermissions</li>
</ul>
<h3 id="232">2.3.2</h3>
<p><strong>Date</strong>: 8th May 2013</p>
<ul>
<li>Bugfix: Fix <code>TIME_FORMAT</code>, <code>DATETIME_FORMAT</code> and <code>DATE_FORMAT</code> settings.</li>
<li>Bugfix: Fix <code>DjangoFilterBackend</code> issue, failing when used on view with queryset attribute.</li>
</ul>
<h3 id="231">2.3.1</h3>
<p><strong>Date</strong>: 7th May 2013</p>
<ul>
<li>Bugfix: Fix breadcrumb rendering issue.</li>
</ul>
<h3 id="230">2.3.0</h3>
<p><strong>Date</strong>: 7th May 2013</p>
<ul>
<li>ViewSets and Routers.</li>
<li>ModelSerializers support reverse relations in 'fields' option.</li>
<li>HyperLinkedModelSerializers support 'id' field in 'fields' option.</li>
<li>Cleaner generic views.</li>
<li>Support for multiple filter classes.</li>
<li>FileUploadParser support for raw file uploads.</li>
<li>DecimalField support.</li>
<li>Made Login template easier to restyle.</li>
<li>Bugfix: Fix issue with depth&gt;1 on ModelSerializer.</li>
</ul>
<p><strong>Note</strong>: See the <a href="../2.3-announcement">2.3 announcement</a> for full details.</p>
<hr />
<h2 id="22x-series">2.2.x series</h2>
<h3 id="227">2.2.7</h3>
<p><strong>Date</strong>: 17th April 2013</p>
<ul>
<li>Loud failure when view does not return a <code>Response</code> or <code>HttpResponse</code>.</li>
<li>Bugfix: Fix for Django 1.3 compatibility.</li>
<li>Bugfix: Allow overridden <code>get_object()</code> to work correctly.</li>
</ul>
<h3 id="226">2.2.6</h3>
<p><strong>Date</strong>: 4th April 2013</p>
<ul>
<li>OAuth2 authentication no longer requires unnecessary URL parameters in addition to the token.</li>
<li>URL hyperlinking in browsable API now handles more cases correctly.</li>
<li>Long HTTP headers in browsable API are broken in multiple lines when possible.</li>
<li>Bugfix: Fix regression with DjangoFilterBackend not worthing correctly with single object views.</li>
<li>Bugfix: OAuth should fail hard when invalid token used.</li>
<li>Bugfix: Fix serializer potentially returning <code>None</code> object for models that define <code>__bool__</code> or <code>__len__</code>.</li>
</ul>
<h3 id="225">2.2.5</h3>
<p><strong>Date</strong>: 26th March 2013</p>
<ul>
<li>Serializer support for bulk create and bulk update operations.</li>
<li>Regression fix: Date and time fields return date/time objects by default. Fixes regressions caused by 2.2.2. See <a href="https://github.com/tomchristie/django-rest-framework/pull/743">#743</a> for more details.</li>
<li>Bugfix: Fix 500 error is OAuth not attempted with OAuthAuthentication class installed.</li>
<li><code>Serializer.save()</code> now supports arbitrary keyword args which are passed through to the object <code>.save()</code> method. Mixins use <code>force_insert</code> and <code>force_update</code> where appropriate, resulting in one less database query.</li>
</ul>
<h3 id="224">2.2.4</h3>
<p><strong>Date</strong>: 13th March 2013</p>
<ul>
<li>OAuth 2 support.</li>
<li>OAuth 1.0a support.</li>
<li>Support X-HTTP-Method-Override header.</li>
<li>Filtering backends are now applied to the querysets for object lookups as well as lists. (Eg you can use a filtering backend to control which objects should 404)</li>
<li>Deal with error data nicely when deserializing lists of objects.</li>
<li>Extra override hook to configure <code>DjangoModelPermissions</code> for unauthenticated users.</li>
<li>Bugfix: Fix regression which caused extra database query on paginated list views.</li>
<li>Bugfix: Fix pk relationship bug for some types of 1-to-1 relations.</li>
<li>Bugfix: Workaround for Django bug causing case where <code>Authtoken</code> could be registered for cascade delete from <code>User</code> even if not installed.</li>
</ul>
<h3 id="223">2.2.3</h3>
<p><strong>Date</strong>: 7th March 2013</p>
<ul>
<li>Bugfix: Fix None values for for <code>DateField</code>, <code>DateTimeField</code> and <code>TimeField</code>.</li>
</ul>
<h3 id="222">2.2.2</h3>
<p><strong>Date</strong>: 6th March 2013</p>
<ul>
<li>Support for custom input and output formats for <code>DateField</code>, <code>DateTimeField</code> and <code>TimeField</code>.</li>
<li>Cleanup: Request authentication is no longer lazily evaluated, instead authentication is always run, which results in more consistent, obvious behavior. Eg. Supplying bad auth credentials will now always return an error response, even if no permissions are set on the view.</li>
<li>Bugfix for serializer data being uncacheable with pickle protocol 0.</li>
<li>Bugfixes for model field validation edge-cases.</li>
<li>Bugfix for authtoken migration while using a custom user model and south.</li>
</ul>
<h3 id="221">2.2.1</h3>
<p><strong>Date</strong>: 22nd Feb 2013</p>
<ul>
<li>Security fix: Use <code>defusedxml</code> package to address XML parsing vulnerabilities.</li>
<li>Raw data tab added to browsable API. (Eg. Allow for JSON input.)</li>
<li>Added TimeField.</li>
<li>Serializer fields can be mapped to any method that takes no args, or only takes kwargs which have defaults.</li>
<li>Unicode support for view names/descriptions in browsable API.</li>
<li>Bugfix: request.DATA should return an empty <code>QueryDict</code> with no data, not <code>None</code>.</li>
<li>Bugfix: Remove unneeded field validation, which caused extra queries.</li>
</ul>
<p><strong>Security note</strong>: Following the <a href="http://blog.python.org/2013/02/announcing-defusedxml-fixes-for-xml.html">disclosure of security vulnerabilities</a> in Python's XML parsing libraries, use of the <code>XMLParser</code> class now requires the <code>defusedxml</code> package to be installed.</p>
<p>The security vulnerabilities only affect APIs which use the <code>XMLParser</code> class, by enabling it in any views, or by having it set in the <code>DEFAULT_PARSER_CLASSES</code> setting. Note that the <code>XMLParser</code> class is not enabled by default, so this change should affect a minority of users.</p>
<h3 id="220">2.2.0</h3>
<p><strong>Date</strong>: 13th Feb 2013</p>
<ul>
<li>Python 3 support.</li>
<li>Added a <code>post_save()</code> hook to the generic views.</li>
<li>Allow serializers to handle dicts as well as objects.</li>
<li>Deprecate <code>ManyRelatedField()</code> syntax in favor of <code>RelatedField(many=True)</code></li>
<li>Deprecate <code>null=True</code> on relations in favor of <code>required=False</code>.</li>
<li>Deprecate <code>blank=True</code> on CharFields, just use <code>required=False</code>.</li>
<li>Deprecate optional <code>obj</code> argument in permissions checks in favor of <code>has_object_permission</code>.</li>
<li>Deprecate implicit hyperlinked relations behavior.</li>
<li>Bugfix: Fix broken DjangoModelPermissions.</li>
<li>Bugfix: Allow serializer output to be cached.</li>
<li>Bugfix: Fix styling on browsable API login.</li>
<li>Bugfix: Fix issue with deserializing empty to-many relations.</li>
<li>Bugfix: Ensure model field validation is still applied for ModelSerializer subclasses with an custom <code>.restore_object()</code> method.</li>
</ul>
<p><strong>Note</strong>: See the <a href="../2.2-announcement">2.2 announcement</a> for full details.</p>
<hr />
<h2 id="21x-series">2.1.x series</h2>
<h3 id="2117">2.1.17</h3>
<p><strong>Date</strong>: 26th Jan 2013</p>
<ul>
<li>Support proper 401 Unauthorized responses where appropriate, instead of always using 403 Forbidden.</li>
<li>Support json encoding of timedelta objects.</li>
<li><code>format_suffix_patterns()</code> now supports <code>include</code> style URL patterns.</li>
<li>Bugfix: Fix issues with custom pagination serializers.</li>
<li>Bugfix: Nested serializers now accept <code>source='*'</code> argument.</li>
<li>Bugfix: Return proper validation errors when incorrect types supplied for relational fields.</li>
<li>Bugfix: Support nullable FKs with <code>SlugRelatedField</code>.</li>
<li>Bugfix: Don't call custom validation methods if the field has an error.</li>
</ul>
<p><strong>Note</strong>: If the primary authentication class is <code>TokenAuthentication</code> or <code>BasicAuthentication</code>, a view will now correctly return 401 responses to unauthenticated access, with an appropriate <code>WWW-Authenticate</code> header, instead of 403 responses.</p>
<h3 id="2116">2.1.16</h3>
<p><strong>Date</strong>: 14th Jan 2013</p>
<ul>
<li>Deprecate <code>django.utils.simplejson</code> in favor of Python 2.6's built-in json module.</li>
<li>Bugfix: <code>auto_now</code>, <code>auto_now_add</code> and other <code>editable=False</code> fields now default to read-only.</li>
<li>Bugfix: PK fields now only default to read-only if they are an AutoField or if <code>editable=False</code>.</li>
<li>Bugfix: Validation errors instead of exceptions when serializers receive incorrect types.</li>
<li>Bugfix: Validation errors instead of exceptions when related fields receive incorrect types.</li>
<li>Bugfix: Handle ObjectDoesNotExist exception when serializing null reverse one-to-one</li>
</ul>
<p><strong>Note</strong>: Prior to 2.1.16, The Decimals would render in JSON using floating point if <code>simplejson</code> was installed, but otherwise render using string notation. Now that use of <code>simplejson</code> has been deprecated, Decimals will consistently render using string notation. See <a href="../../ticket-582">ticket 582</a> for more details.</p>
<h3 id="2115">2.1.15</h3>
<p><strong>Date</strong>: 3rd Jan 2013</p>
<ul>
<li>Added <code>PATCH</code> support.</li>
<li>Added <code>RetrieveUpdateAPIView</code>.</li>
<li>Remove unused internal <code>save_m2m</code> flag on <code>ModelSerializer.save()</code>.</li>
<li>Tweak behavior of hyperlinked fields with an explicit format suffix.</li>
<li>Relation changes are now persisted in <code>.save()</code> instead of in <code>.restore_object()</code>.</li>
<li>Bugfix: Fix issue with FileField raising exception instead of validation error when files=None.</li>
<li>Bugfix: Partial updates should not set default values if field is not included.</li>
</ul>
<h3 id="2114">2.1.14</h3>
<p><strong>Date</strong>: 31st Dec 2012</p>
<ul>
<li>Bugfix: ModelSerializers now include reverse FK fields on creation.</li>
<li>Bugfix: Model fields with <code>blank=True</code> are now <code>required=False</code> by default.</li>
<li>Bugfix: Nested serializers now support nullable relationships.</li>
</ul>
<p><strong>Note</strong>: From 2.1.14 onwards, relational fields move out of the <code>fields.py</code> module and into the new <code>relations.py</code> module, in order to separate them from regular data type fields, such as <code>CharField</code> and <code>IntegerField</code>.</p>
<p>This change will not affect user code, so long as it's following the recommended import style of <code>from rest_framework import serializers</code> and referring to fields using the style <code>serializers.PrimaryKeyRelatedField</code>.</p>
<h3 id="2113">2.1.13</h3>
<p><strong>Date</strong>: 28th Dec 2012</p>
<ul>
<li>Support configurable <code>STATICFILES_STORAGE</code> storage.</li>
<li>Bugfix: Related fields now respect the required flag, and may be required=False.</li>
</ul>
<h3 id="2112">2.1.12</h3>
<p><strong>Date</strong>: 21st Dec 2012</p>
<ul>
<li>Bugfix: Fix bug that could occur using ChoiceField.</li>
<li>Bugfix: Fix exception in browsable API on DELETE.</li>
<li>Bugfix: Fix issue where pk was was being set to a string if set by URL kwarg.</li>
</ul>
<h3 id="2111">2.1.11</h3>
<p><strong>Date</strong>: 17th Dec 2012</p>
<ul>
<li>Bugfix: Fix issue with M2M fields in browsable API.</li>
</ul>
<h3 id="2110">2.1.10</h3>
<p><strong>Date</strong>: 17th Dec 2012</p>
<ul>
<li>Bugfix: Ensure read-only fields don't have model validation applied.</li>
<li>Bugfix: Fix hyperlinked fields in paginated results.</li>
</ul>
<h3 id="219">2.1.9</h3>
<p><strong>Date</strong>: 11th Dec 2012</p>
<ul>
<li>Bugfix: Fix broken nested serialization.</li>
<li>Bugfix: Fix <code>Meta.fields</code> only working as tuple not as list.</li>
<li>Bugfix: Edge case if unnecessarily specifying <code>required=False</code> on read only field.</li>
</ul>
<h3 id="218">2.1.8</h3>
<p><strong>Date</strong>: 8th Dec 2012</p>
<ul>
<li>Fix for creating nullable Foreign Keys with <code>''</code> as well as <code>None</code>.</li>
<li>Added <code>null=&lt;bool&gt;</code> related field option.</li>
</ul>
<h3 id="217">2.1.7</h3>
<p><strong>Date</strong>: 7th Dec 2012</p>
<ul>
<li>Serializers now properly support nullable Foreign Keys.</li>
<li>Serializer validation now includes model field validation, such as uniqueness constraints.</li>
<li>Support 'true' and 'false' string values for BooleanField.</li>
<li>Added pickle support for serialized data.</li>
<li>Support <code>source='dotted.notation'</code> style for nested serializers.</li>
<li>Make <code>Request.user</code> settable.</li>
<li>Bugfix: Fix <code>RegexField</code> to work with <code>BrowsableAPIRenderer</code>.</li>
</ul>
<h3 id="216">2.1.6</h3>
<p><strong>Date</strong>: 23rd Nov 2012</p>
<ul>
<li>Bugfix: Unfix DjangoModelPermissions. (I am a doofus.)</li>
</ul>
<h3 id="215">2.1.5</h3>
<p><strong>Date</strong>: 23rd Nov 2012</p>
<ul>
<li>Bugfix: Fix DjangoModelPermissions.</li>
</ul>
<h3 id="214">2.1.4</h3>
<p><strong>Date</strong>: 22nd Nov 2012</p>
<ul>
<li>Support for partial updates with serializers.</li>
<li>Added <code>RegexField</code>.</li>
<li>Added <code>SerializerMethodField</code>.</li>
<li>Serializer performance improvements.</li>
<li>Added <code>obtain_token_view</code> to get tokens when using <code>TokenAuthentication</code>.</li>
<li>Bugfix: Django 1.5 configurable user support for <code>TokenAuthentication</code>.</li>
</ul>
<h3 id="213">2.1.3</h3>
<p><strong>Date</strong>: 16th Nov 2012</p>
<ul>
<li>Added <code>FileField</code> and <code>ImageField</code>. For use with <code>MultiPartParser</code>.</li>
<li>Added <code>URLField</code> and <code>SlugField</code>.</li>
<li>Support for <code>read_only_fields</code> on <code>ModelSerializer</code> classes.</li>
<li>Support for clients overriding the pagination page sizes. Use the <code>PAGINATE_BY_PARAM</code> setting or set the <code>paginate_by_param</code> attribute on a generic view.</li>
<li>201 Responses now return a 'Location' header.</li>
<li>Bugfix: Serializer fields now respect <code>max_length</code>.</li>
</ul>
<h3 id="212">2.1.2</h3>
<p><strong>Date</strong>: 9th Nov 2012</p>
<ul>
<li><strong>Filtering support.</strong></li>
<li>Bugfix: Support creation of objects with reverse M2M relations.</li>
</ul>
<h3 id="211">2.1.1</h3>
<p><strong>Date</strong>: 7th Nov 2012</p>
<ul>
<li>Support use of HTML exception templates. Eg. <code>403.html</code></li>
<li>Hyperlinked fields take optional <code>slug_field</code>, <code>slug_url_kwarg</code> and <code>pk_url_kwarg</code> arguments.</li>
<li>Bugfix: Deal with optional trailing slashes properly when generating breadcrumbs.</li>
<li>Bugfix: Make textareas same width as other fields in browsable API.</li>
<li>Private API change: <code>.get_serializer</code> now uses same <code>instance</code> and <code>data</code> ordering as serializer initialization.</li>
</ul>
<h3 id="210">2.1.0</h3>
<p><strong>Date</strong>: 5th Nov 2012</p>
<ul>
<li><strong>Serializer <code>instance</code> and <code>data</code> keyword args have their position swapped.</strong></li>
<li><code>queryset</code> argument is now optional on writable model fields.</li>
<li>Hyperlinked related fields optionally take <code>slug_field</code> and <code>slug_url_kwarg</code> arguments.</li>
<li>Support Django's cache framework.</li>
<li>Minor field improvements. (Don't stringify dicts, more robust many-pk fields.)</li>
<li>Bugfix: Support choice field in Browsable API.</li>
<li>Bugfix: Related fields with <code>read_only=True</code> do not require a <code>queryset</code> argument.</li>
</ul>
<p><strong>API-incompatible changes</strong>: Please read <a href="https://groups.google.com/d/topic/django-rest-framework/Vv2M0CMY9bg/discussion">this thread</a> regarding the <code>instance</code> and <code>data</code> keyword args before updating to 2.1.0.</p>
<hr />
<h2 id="20x-series">2.0.x series</h2>
<h3 id="202">2.0.2</h3>
<p><strong>Date</strong>: 2nd Nov 2012</p>
<ul>
<li>Fix issues with pk related fields in the browsable API.</li>
</ul>
<h3 id="201">2.0.1</h3>
<p><strong>Date</strong>: 1st Nov 2012</p>
<ul>
<li>Add support for relational fields in the browsable API.</li>
<li>Added SlugRelatedField and ManySlugRelatedField.</li>
<li>If PUT creates an instance return '201 Created', instead of '200 OK'.</li>
</ul>
<h3 id="200">2.0.0</h3>
<p><strong>Date</strong>: 30th Oct 2012</p>
<ul>
<li><strong>Fix all of the things.</strong> (Well, almost.)</li>
<li>For more information please see the <a href="../rest-framework-2-announcement">2.0 announcement</a>.</li>
</ul>
<p>For older release notes, <a href="../../old-release-notes">please see the GitHub repo</a>.</p>
<p>For older release notes, <a href="../../old-release-notes">please see the version 2.x documentation</a>.</p>
<!-- 3.0.1 -->
<p><!-- 3.0.2 -->
......
topics/rest-hypermedia-hateoas/index.html
......@@ -189,6 +189,10 @@
</li>
<li >
<a href="../../api-guide/versioning">Versioning</a>
</li>
<li >
<a href="../../api-guide/content-negotiation">Content negotiation</a>
</li>
......@@ -232,6 +236,10 @@
</li>
<li >
<a href="../internationalization">Internationalization</a>
</li>
<li >
<a href="../ajax-csrf-cors">AJAX, CSRF & CORS</a>
</li>
......@@ -260,23 +268,11 @@
</li>
<li >
<a href="../rest-framework-2-announcement">2.0 Announcement</a>
</li>
<li >
<a href="../2.2-announcement">2.2 Announcement</a>
</li>
<li >
<a href="../2.3-announcement">2.3 Announcement</a>
</li>
<li >
<a href="../2.4-announcement">2.4 Announcement</a>
<a href="../3.0-announcement">3.0 Announcement</a>
</li>
<li >
<a href="../3.0-announcement">3.0 Announcement</a>
<a href="../3.1-announcement">3.1 Announcement</a>
</li>
<li >
......@@ -287,10 +283,6 @@
<a href="../release-notes">Release Notes</a>
</li>
<li >
<a href="../credits">Credits</a>
</li>
</ul>
</li>
......
topics/third-party-resources/index.html
......@@ -189,6 +189,10 @@
</li>
<li >
<a href="../../api-guide/versioning">Versioning</a>
</li>
<li >
<a href="../../api-guide/content-negotiation">Content negotiation</a>
</li>
......@@ -232,6 +236,10 @@
</li>
<li >
<a href="../internationalization">Internationalization</a>
</li>
<li >
<a href="../ajax-csrf-cors">AJAX, CSRF & CORS</a>
</li>
......@@ -260,23 +268,11 @@
</li>
<li >
<a href="../rest-framework-2-announcement">2.0 Announcement</a>
</li>
<li >
<a href="../2.2-announcement">2.2 Announcement</a>
</li>
<li >
<a href="../2.3-announcement">2.3 Announcement</a>
</li>
<li >
<a href="../2.4-announcement">2.4 Announcement</a>
<a href="../3.0-announcement">3.0 Announcement</a>
</li>
<li >
<a href="../3.0-announcement">3.0 Announcement</a>
<a href="../3.1-announcement">3.1 Announcement</a>
</li>
<li >
......@@ -287,10 +283,6 @@
<a href="../release-notes">Release Notes</a>
</li>
<li >
<a href="../credits">Credits</a>
</li>
</ul>
</li>
......@@ -512,6 +504,7 @@ You probably want to also tag the version now:
<li><a href="https://github.com/kumar303/hawkrest">hawkrest</a> - Provides Hawk HTTP Authorization.</li>
<li><a href="https://github.com/etoccalino/django-rest-framework-httpsignature">djangorestframework-httpsignature</a> - Provides an easy to use HTTP Signature Authentication mechanism.</li>
<li><a href="https://github.com/sunscrapers/djoser">djoser</a> - Provides a set of views to handle basic actions such as registration, login, logout, password reset and account activation.</li>
<li><a href="https://github.com/Tivix/django-rest-auth/">django-rest-auth</a> - Provides a set of REST API endpoints for registration, authentication (including social media authentication), password reset, retrieve and update user details, etc.</li>
</ul>
<h3 id="permissions">Permissions</h3>
<ul>
......
tutorial/1-serialization/index.html
......@@ -189,6 +189,10 @@
</li>
<li >
<a href="../../api-guide/versioning">Versioning</a>
</li>
<li >
<a href="../../api-guide/content-negotiation">Content negotiation</a>
</li>
......@@ -232,6 +236,10 @@
</li>
<li >
<a href="../../topics/internationalization">Internationalization</a>
</li>
<li >
<a href="../../topics/ajax-csrf-cors">AJAX, CSRF & CORS</a>
</li>
......@@ -260,23 +268,11 @@
</li>
<li >
<a href="../../topics/rest-framework-2-announcement">2.0 Announcement</a>
</li>
<li >
<a href="../../topics/2.2-announcement">2.2 Announcement</a>
</li>
<li >
<a href="../../topics/2.3-announcement">2.3 Announcement</a>
</li>
<li >
<a href="../../topics/2.4-announcement">2.4 Announcement</a>
<a href="../../topics/3.0-announcement">3.0 Announcement</a>
</li>
<li >
<a href="../../topics/3.0-announcement">3.0 Announcement</a>
<a href="../../topics/3.1-announcement">3.1 Announcement</a>
</li>
<li >
......@@ -287,10 +283,6 @@
<a href="../../topics/release-notes">Release Notes</a>
</li>
<li >
<a href="../../topics/credits">Credits</a>
</li>
</ul>
</li>
......
tutorial/2-requests-and-responses/index.html
......@@ -189,6 +189,10 @@
</li>
<li >
<a href="../../api-guide/versioning">Versioning</a>
</li>
<li >
<a href="../../api-guide/content-negotiation">Content negotiation</a>
</li>
......@@ -232,6 +236,10 @@
</li>
<li >
<a href="../../topics/internationalization">Internationalization</a>
</li>
<li >
<a href="../../topics/ajax-csrf-cors">AJAX, CSRF & CORS</a>
</li>
......@@ -260,23 +268,11 @@
</li>
<li >
<a href="../../topics/rest-framework-2-announcement">2.0 Announcement</a>
</li>
<li >
<a href="../../topics/2.2-announcement">2.2 Announcement</a>
</li>
<li >
<a href="../../topics/2.3-announcement">2.3 Announcement</a>
</li>
<li >
<a href="../../topics/2.4-announcement">2.4 Announcement</a>
<a href="../../topics/3.0-announcement">3.0 Announcement</a>
</li>
<li >
<a href="../../topics/3.0-announcement">3.0 Announcement</a>
<a href="../../topics/3.1-announcement">3.1 Announcement</a>
</li>
<li >
......@@ -287,10 +283,6 @@
<a href="../../topics/release-notes">Release Notes</a>
</li>
<li >
<a href="../../topics/credits">Credits</a>
</li>
</ul>
</li>
......@@ -479,7 +471,7 @@ def snippet_detail(request, pk):
return Response(status=status.HTTP_204_NO_CONTENT)
</code></pre>
<p>This should all feel very familiar - it is not a lot different from working with regular Django views.</p>
<p>Notice that we're no longer explicitly tying our requests or responses to a given content type. <code>request.data</code> can handle incoming <code>json</code> requests, but it can also handle <code>yaml</code> and other formats. Similarly we're returning response objects with data, but allowing REST framework to render the response into the correct content type for us.</p>
<p>Notice that we're no longer explicitly tying our requests or responses to a given content type. <code>request.data</code> can handle incoming <code>json</code> requests, but it can also handle other formats. Similarly we're returning response objects with data, but allowing REST framework to render the response into the correct content type for us.</p>
<h2 id="adding-optional-format-suffixes-to-our-urls">Adding optional format suffixes to our URLs</h2>
<p>To take advantage of the fact that our responses are no longer hardwired to a single content type let's add support for format suffixes to our API endpoints. Using format suffixes gives us URLs that explicitly refer to a given format, and means our API will be able to handle URLs such as <a href="http://example.com/api/items/4.json">http://example.com/api/items/4/.json</a>.</p>
<p>Start by adding a <code>format</code> keyword argument to both of the views, like so.</p>
......
tutorial/3-class-based-views/index.html
......@@ -189,6 +189,10 @@
</li>
<li >
<a href="../../api-guide/versioning">Versioning</a>
</li>
<li >
<a href="../../api-guide/content-negotiation">Content negotiation</a>
</li>
......@@ -232,6 +236,10 @@
</li>
<li >
<a href="../../topics/internationalization">Internationalization</a>
</li>
<li >
<a href="../../topics/ajax-csrf-cors">AJAX, CSRF & CORS</a>
</li>
......@@ -260,23 +268,11 @@
</li>
<li >
<a href="../../topics/rest-framework-2-announcement">2.0 Announcement</a>
</li>
<li >
<a href="../../topics/2.2-announcement">2.2 Announcement</a>
</li>
<li >
<a href="../../topics/2.3-announcement">2.3 Announcement</a>
</li>
<li >
<a href="../../topics/2.4-announcement">2.4 Announcement</a>
<a href="../../topics/3.0-announcement">3.0 Announcement</a>
</li>
<li >
<a href="../../topics/3.0-announcement">3.0 Announcement</a>
<a href="../../topics/3.1-announcement">3.1 Announcement</a>
</li>
<li >
......@@ -287,10 +283,6 @@
<a href="../../topics/release-notes">Release Notes</a>
</li>
<li >
<a href="../../topics/credits">Credits</a>
</li>
</ul>
</li>
......
tutorial/4-authentication-and-permissions/index.html
......@@ -189,6 +189,10 @@
</li>
<li >
<a href="../../api-guide/versioning">Versioning</a>
</li>
<li >
<a href="../../api-guide/content-negotiation">Content negotiation</a>
</li>
......@@ -232,6 +236,10 @@
</li>
<li >
<a href="../../topics/internationalization">Internationalization</a>
</li>
<li >
<a href="../../topics/ajax-csrf-cors">AJAX, CSRF & CORS</a>
</li>
......@@ -260,23 +268,11 @@
</li>
<li >
<a href="../../topics/rest-framework-2-announcement">2.0 Announcement</a>
</li>
<li >
<a href="../../topics/2.2-announcement">2.2 Announcement</a>
</li>
<li >
<a href="../../topics/2.3-announcement">2.3 Announcement</a>
</li>
<li >
<a href="../../topics/2.4-announcement">2.4 Announcement</a>
<a href="../../topics/3.0-announcement">3.0 Announcement</a>
</li>
<li >
<a href="../../topics/3.0-announcement">3.0 Announcement</a>
<a href="../../topics/3.1-announcement">3.1 Announcement</a>
</li>
<li >
......@@ -287,10 +283,6 @@
<a href="../../topics/release-notes">Release Notes</a>
</li>
<li >
<a href="../../topics/credits">Credits</a>
</li>
</ul>
</li>
......
tutorial/5-relationships-and-hyperlinked-apis/index.html
......@@ -189,6 +189,10 @@
</li>
<li >
<a href="../../api-guide/versioning">Versioning</a>
</li>
<li >
<a href="../../api-guide/content-negotiation">Content negotiation</a>
</li>
......@@ -232,6 +236,10 @@
</li>
<li >
<a href="../../topics/internationalization">Internationalization</a>
</li>
<li >
<a href="../../topics/ajax-csrf-cors">AJAX, CSRF & CORS</a>
</li>
......@@ -260,23 +268,11 @@
</li>
<li >
<a href="../../topics/rest-framework-2-announcement">2.0 Announcement</a>
</li>
<li >
<a href="../../topics/2.2-announcement">2.2 Announcement</a>
</li>
<li >
<a href="../../topics/2.3-announcement">2.3 Announcement</a>
</li>
<li >
<a href="../../topics/2.4-announcement">2.4 Announcement</a>
<a href="../../topics/3.0-announcement">3.0 Announcement</a>
</li>
<li >
<a href="../../topics/3.0-announcement">3.0 Announcement</a>
<a href="../../topics/3.1-announcement">3.1 Announcement</a>
</li>
<li >
......@@ -287,10 +283,6 @@
<a href="../../topics/release-notes">Release Notes</a>
</li>
<li >
<a href="../../topics/credits">Credits</a>
</li>
</ul>
</li>
......@@ -514,7 +506,7 @@ urlpatterns += [
<p>The list views for users and code snippets could end up returning quite a lot of instances, so really we'd like to make sure we paginate the results, and allow the API client to step through each of the individual pages.</p>
<p>We can change the default list style to use pagination, by modifying our <code>tutorial/settings.py</code> file slightly. Add the following setting:</p>
<pre><code>REST_FRAMEWORK = {
'PAGINATE_BY': 10
'PAGE_SIZE': 10
}
</code></pre>
<p>Note that settings in REST framework are all namespaced into a single dictionary setting, named 'REST_FRAMEWORK', which helps keep them well separated from your other project settings.</p>
......
tutorial/6-viewsets-and-routers/index.html
......@@ -189,6 +189,10 @@
</li>
<li >
<a href="../../api-guide/versioning">Versioning</a>
</li>
<li >
<a href="../../api-guide/content-negotiation">Content negotiation</a>
</li>
......@@ -232,6 +236,10 @@
</li>
<li >
<a href="../../topics/internationalization">Internationalization</a>
</li>
<li >
<a href="../../topics/ajax-csrf-cors">AJAX, CSRF & CORS</a>
</li>
......@@ -260,23 +268,11 @@
</li>
<li >
<a href="../../topics/rest-framework-2-announcement">2.0 Announcement</a>
</li>
<li >
<a href="../../topics/2.2-announcement">2.2 Announcement</a>
</li>
<li >
<a href="../../topics/2.3-announcement">2.3 Announcement</a>
</li>
<li >
<a href="../../topics/2.4-announcement">2.4 Announcement</a>
<a href="../../topics/3.0-announcement">3.0 Announcement</a>
</li>
<li >
<a href="../../topics/3.0-announcement">3.0 Announcement</a>
<a href="../../topics/3.1-announcement">3.1 Announcement</a>
</li>
<li >
......@@ -287,10 +283,6 @@
<a href="../../topics/release-notes">Release Notes</a>
</li>
<li >
<a href="../../topics/credits">Credits</a>
</li>
</ul>
</li>
......
tutorial/quickstart/index.html
......@@ -189,6 +189,10 @@
</li>
<li >
<a href="../../api-guide/versioning">Versioning</a>
</li>
<li >
<a href="../../api-guide/content-negotiation">Content negotiation</a>
</li>
......@@ -232,6 +236,10 @@
</li>
<li >
<a href="../../topics/internationalization">Internationalization</a>
</li>
<li >
<a href="../../topics/ajax-csrf-cors">AJAX, CSRF & CORS</a>
</li>
......@@ -260,23 +268,11 @@
</li>
<li >
<a href="../../topics/rest-framework-2-announcement">2.0 Announcement</a>
</li>
<li >
<a href="../../topics/2.2-announcement">2.2 Announcement</a>
</li>
<li >
<a href="../../topics/2.3-announcement">2.3 Announcement</a>
</li>
<li >
<a href="../../topics/2.4-announcement">2.4 Announcement</a>
<a href="../../topics/3.0-announcement">3.0 Announcement</a>
</li>
<li >
<a href="../../topics/3.0-announcement">3.0 Announcement</a>
<a href="../../topics/3.1-announcement">3.1 Announcement</a>
</li>
<li >
......@@ -287,10 +283,6 @@
<a href="../../topics/release-notes">Release Notes</a>
</li>
<li >
<a href="../../topics/credits">Credits</a>
</li>
</ul>
</li>
......@@ -496,7 +488,7 @@ urlpatterns = [
REST_FRAMEWORK = {
'DEFAULT_PERMISSION_CLASSES': ('rest_framework.permissions.IsAdminUser',),
'PAGINATE_BY': 10
'PAGE_SIZE': 10
}
</code></pre>
<p>Okay, we're done.</p>
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment