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

Deployed d3f3c3d9 with MkDocs version: 0.16.3

Browse Source
This commit is contained in:
Carlton Gibson 2018-01-15 15:42:44 +01:00
parent 077eb09070
commit 7931ed8d5b
43 changed files with 291 additions and 219 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -512,7 +512,7 @@
<h1 id="authentication"><a class="toclink" href="#authentication">Authentication</a></h1>
<blockquote>
<p>Auth needs to be pluggable.</p>
<p>&mdash; Jacob Kaplan-Moss, <a href="http://jacobian.org/writing/rest-worst-practices/">"REST worst practices"</a></p>
<p>&mdash; Jacob Kaplan-Moss, <a href="https://jacobian.org/writing/rest-worst-practices/">"REST worst practices"</a></p>
</blockquote>
<p>Authentication is the mechanism of associating an incoming request with a set of identifying credentials, such as the user the request came from, or the token that it was signed with. The <a href="../permissions/">permission</a> and <a href="../throttling/">throttling</a> policies can then use those credentials to determine if the request should be permitted.</p>
<p>REST framework provides a number of authentication schemes out of the box, and also allows you to implement custom schemes.</p>
@ -568,14 +568,14 @@ def example_view(request, format=None):
<h2 id="unauthorized-and-forbidden-responses"><a class="toclink" href="#unauthorized-and-forbidden-responses">Unauthorized and Forbidden responses</a></h2>
<p>When an unauthenticated request is denied permission there are two different error codes that may be appropriate.</p>
<ul>
<li><a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2">HTTP 401 Unauthorized</a></li>
<li><a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4">HTTP 403 Permission Denied</a></li>
<li><a href="https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2">HTTP 401 Unauthorized</a></li>
<li><a href="https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4">HTTP 403 Permission Denied</a></li>
</ul>
<p>HTTP 401 responses must always include a <code>WWW-Authenticate</code> header, that instructs the client how to authenticate. HTTP 403 responses do not include the <code>WWW-Authenticate</code> header.</p>
<p>The kind of response that will be used depends on the authentication scheme. Although multiple authentication schemes may be in use, only one scheme may be used to determine the type of response. <strong>The first authentication class set on the view is used when determining the type of response</strong>.</p>
<p>Note that when a request may successfully authenticate, but still be denied permission to perform the request, in which case a <code>403 Permission Denied</code> response will always be used, regardless of the authentication scheme.</p>
<h2 id="apache-mod_wsgi-specific-configuration"><a class="toclink" href="#apache-mod_wsgi-specific-configuration">Apache mod_wsgi specific configuration</a></h2>
<p>Note that if deploying to <a href="http://code.google.com/p/modwsgi/wiki/ConfigurationDirectives#WSGIPassAuthorization">Apache using mod_wsgi</a>, the authorization header is not passed through to a WSGI application by default, as it is assumed that authentication will be handled by Apache, rather than at an application level.</p>
<p>Note that if deploying to <a href="https://modwsgi.readthedocs.io/en/develop/configuration-directives/WSGIPassAuthorization.html">Apache using mod_wsgi</a>, the authorization header is not passed through to a WSGI application by default, as it is assumed that authentication will be handled by Apache, rather than at an application level.</p>
<p>If you are deploying to Apache, and using any non-session based authentication, you will need to explicitly configure mod_wsgi to pass the required headers through to the application. This can be done by specifying the <code>WSGIPassAuthorization</code> directive in the appropriate context and setting it to <code>'On'</code>.</p>
<pre><code># this can go in either server config, virtual host, directory or .htaccess
WSGIPassAuthorization On
@ -583,7 +583,7 @@ WSGIPassAuthorization On
<hr />
<h1 id="api-reference"><a class="toclink" href="#api-reference">API Reference</a></h1>
<h2 id="basicauthentication"><a class="toclink" href="#basicauthentication">BasicAuthentication</a></h2>
<p>This authentication scheme uses <a href="http://tools.ietf.org/html/rfc2617">HTTP Basic Authentication</a>, signed against a user's username and password. Basic authentication is generally only appropriate for testing.</p>
<p>This authentication scheme uses <a href="https://tools.ietf.org/html/rfc2617">HTTP Basic Authentication</a>, signed against a user's username and password. Basic authentication is generally only appropriate for testing.</p>
<p>If successfully authenticated, <code>BasicAuthentication</code> provides the following credentials.</p>
<ul>
<li><code>request.user</code> will be a Django <code>User</code> instance.</li>
@ -763,13 +763,13 @@ REST_FRAMEWORK = {
</code></pre>
<p>For more details see the <a href="https://django-oauth-toolkit.readthedocs.io/en/latest/rest-framework/getting_started.html">Django REST framework - Getting started</a> documentation.</p>
<h2 id="django-rest-framework-oauth"><a class="toclink" href="#django-rest-framework-oauth">Django REST framework OAuth</a></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>The <a href="https://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"><a class="toclink" href="#installation-configuration_1">Installation &amp; configuration</a></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>
<p>For details on configuration and usage see the Django REST framework OAuth documentation for <a href="https://jpadilla.github.io/django-rest-framework-oauth/authentication/">authentication</a> and <a href="https://jpadilla.github.io/django-rest-framework-oauth/permissions/">permissions</a>.</p>
<h2 id="digest-authentication"><a class="toclink" href="#digest-authentication">Digest Authentication</a></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-oauth2-consumer"><a class="toclink" href="#django-oauth2-consumer">Django OAuth2 Consumer</a></h2>
@ -777,9 +777,9 @@ REST_FRAMEWORK = {
<h2 id="json-web-token-authentication"><a class="toclink" href="#json-web-token-authentication">JSON Web Token Authentication</a></h2>
<p>JSON Web Token is a fairly new standard which can be used for token-based authentication. Unlike the built-in TokenAuthentication scheme, JWT Authentication doesn't need to use a database to validate a token. <a href="https://github.com/GetBlimp">Blimp</a> maintains the <a href="https://github.com/GetBlimp/django-rest-framework-jwt">djangorestframework-jwt</a> package which provides a JWT Authentication class as well as a mechanism for clients to obtain a JWT given the username and password. An alternative package for JWT authentication is <a href="https://github.com/davesque/django-rest-framework-simplejwt">djangorestframework-simplejwt</a> which provides different features as well as a pluggable token blacklist app.</p>
<h2 id="hawk-http-authentication"><a class="toclink" href="#hawk-http-authentication">Hawk HTTP Authentication</a></h2>
<p>The <a href="https://hawkrest.readthedocs.io/en/latest/">HawkREST</a> library builds on the <a href="https://mohawk.readthedocs.io/en/latest/">Mohawk</a> library to let you work with <a href="https://github.com/hueniverse/hawk">Hawk</a> signed requests and responses in your API. <a href="https://github.com/hueniverse/hawk">Hawk</a> lets two parties securely communicate with each other using messages signed by a shared key. It is based on <a href="http://tools.ietf.org/html/draft-hammer-oauth-v2-mac-token-05">HTTP MAC access authentication</a> (which was based on parts of <a href="http://oauth.net/core/1.0a">OAuth 1.0</a>).</p>
<p>The <a href="https://hawkrest.readthedocs.io/en/latest/">HawkREST</a> library builds on the <a href="https://mohawk.readthedocs.io/en/latest/">Mohawk</a> library to let you work with <a href="https://github.com/hueniverse/hawk">Hawk</a> signed requests and responses in your API. <a href="https://github.com/hueniverse/hawk">Hawk</a> lets two parties securely communicate with each other using messages signed by a shared key. It is based on <a href="https://tools.ietf.org/html/draft-hammer-oauth-v2-mac-token-05">HTTP MAC access authentication</a> (which was based on parts of <a href="https://oauth.net/core/1.0a/">OAuth 1.0</a>).</p>
<h2 id="http-signature-authentication"><a class="toclink" href="#http-signature-authentication">HTTP Signature Authentication</a></h2>
<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>
<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="https://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"><a class="toclink" href="#djoser">Djoser</a></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"><a class="toclink" href="#django-rest-auth">django-rest-auth</a></h2>

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

@ -428,7 +428,7 @@
<h1 id="content-negotiation"><a class="toclink" href="#content-negotiation">Content negotiation</a></h1>
<blockquote>
<p>HTTP has provisions for several mechanisms for "content negotiation" - the process of selecting the best representation for a given response when there are multiple representations available.</p>
<p>&mdash; <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html">RFC 2616</a>, Fielding et al.</p>
<p>&mdash; <a href="https://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html">RFC 2616</a>, Fielding et al.</p>
</blockquote>
<p>Content negotiation is the process of selecting one of multiple possible representations to return to a client, based on client or server preferences.</p>
<h2 id="determining-the-accepted-renderer"><a class="toclink" href="#determining-the-accepted-renderer">Determining the accepted renderer</a></h2>
@ -447,7 +447,7 @@
<li><code>*/*</code></li>
</ul>
<p>If the requested view was only configured with renderers for <code>YAML</code> and <code>HTML</code>, then REST framework would select whichever renderer was listed first in the <code>renderer_classes</code> list or <code>DEFAULT_RENDERER_CLASSES</code> setting.</p>
<p>For more information on the <code>HTTP Accept</code> header, see <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html">RFC 2616</a></p>
<p>For more information on the <code>HTTP Accept</code> header, see <a href="https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html">RFC 2616</a></p>
<hr />
<p><strong>Note</strong>: "q" values are not taken into account by REST framework when determining preference. The use of "q" values negatively impacts caching, and in the author's opinion they are an unnecessary and overcomplicated approach to content negotiation.</p>
<p>This is a valid approach as the HTTP spec deliberately underspecifies how a server should weight server-based preferences against client-based preferences.</p>

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

@ -636,7 +636,7 @@ Set to false if this field is not required to be present during deserialization.
<p>Defaults to <code>True</code>.</p>
<h3 id="allow_null"><a class="toclink" href="#allow_null"><code>allow_null</code></a></h3>
<p>Normally an error will be raised if <code>None</code> is passed to a serializer field. Set this keyword argument to <code>True</code> if <code>None</code> should be considered a valid value.</p>
<p>Note that setting this argument to <code>True</code> will imply a default value of <code>null</code> for serialization output, but does imply a default for input deserialization.</p>
<p>Note that setting this argument to <code>True</code> will imply a default value of <code>null</code> for serialization output, but does not imply a default for input deserialization.</p>
<p>Defaults to <code>False</code></p>
<h3 id="default"><a class="toclink" href="#default"><code>default</code></a></h3>
<p>If set, this gives the default value that will be used for the field if no input value is supplied. If not set the default behaviour is to not populate the attribute at all.</p>
@ -807,7 +807,7 @@ color_channel = serializers.ChoiceField(
<li><code>input_formats</code> - A list of strings representing the input formats which may be used to parse the date. If not specified, the <code>DATETIME_INPUT_FORMATS</code> setting will be used, which defaults to <code>['iso-8601']</code>.</li>
</ul>
<h4 id="datetimefield-format-strings"><a class="toclink" href="#datetimefield-format-strings"><code>DateTimeField</code> format strings.</a></h4>
<p>Format strings may either be <a href="https://docs.python.org/3/library/datetime.html#strftime-and-strptime-behavior">Python strftime formats</a> which explicitly specify the format, or the special string <code>'iso-8601'</code>, which indicates that <a href="http://www.w3.org/TR/NOTE-datetime">ISO 8601</a> style datetimes should be used. (eg <code>'2013-01-29T12:34:56.000000Z'</code>)</p>
<p>Format strings may either be <a href="https://docs.python.org/3/library/datetime.html#strftime-and-strptime-behavior">Python strftime formats</a> which explicitly specify the format, or the special string <code>'iso-8601'</code>, which indicates that <a href="https://www.w3.org/TR/NOTE-datetime">ISO 8601</a> style datetimes should be used. (eg <code>'2013-01-29T12:34:56.000000Z'</code>)</p>
<p>When a value of <code>None</code> is used for the format <code>datetime</code> objects will be returned by <code>to_representation</code> and the final output representation will determined by the renderer class.</p>
<h4 id="auto_now-and-auto_now_add-model-fields"><code>auto_now_add</code> model fields.<a class="toclink" href="#auto_now-and-auto_now_add-model-fields"><code>auto_now</code> and </a></h4>
<p>When using <code>ModelSerializer</code> or <code>HyperlinkedModelSerializer</code>, note that any model fields with <code>auto_now=True</code> or <code>auto_now_add=True</code> will use serializer fields that are <code>read_only=True</code> by default.</p>
@ -827,7 +827,7 @@ color_channel = serializers.ChoiceField(
<li><code>input_formats</code> - A list of strings representing the input formats which may be used to parse the date. If not specified, the <code>DATE_INPUT_FORMATS</code> setting will be used, which defaults to <code>['iso-8601']</code>.</li>
</ul>
<h4 id="datefield-format-strings"><a class="toclink" href="#datefield-format-strings"><code>DateField</code> format strings</a></h4>
<p>Format strings may either be <a href="https://docs.python.org/3/library/datetime.html#strftime-and-strptime-behavior">Python strftime formats</a> which explicitly specify the format, or the special string <code>'iso-8601'</code>, which indicates that <a href="http://www.w3.org/TR/NOTE-datetime">ISO 8601</a> style dates should be used. (eg <code>'2013-01-29'</code>)</p>
<p>Format strings may either be <a href="https://docs.python.org/3/library/datetime.html#strftime-and-strptime-behavior">Python strftime formats</a> which explicitly specify the format, or the special string <code>'iso-8601'</code>, which indicates that <a href="https://www.w3.org/TR/NOTE-datetime">ISO 8601</a> style dates should be used. (eg <code>'2013-01-29'</code>)</p>
<h2 id="timefield"><a class="toclink" href="#timefield">TimeField</a></h2>
<p>A time representation.</p>
<p>Corresponds to <code>django.db.models.fields.TimeField</code></p>
@ -837,7 +837,7 @@ color_channel = serializers.ChoiceField(
<li><code>input_formats</code> - A list of strings representing the input formats which may be used to parse the date. If not specified, the <code>TIME_INPUT_FORMATS</code> setting will be used, which defaults to <code>['iso-8601']</code>.</li>
</ul>
<h4 id="timefield-format-strings"><a class="toclink" href="#timefield-format-strings"><code>TimeField</code> format strings</a></h4>
<p>Format strings may either be <a href="https://docs.python.org/3/library/datetime.html#strftime-and-strptime-behavior">Python strftime formats</a> which explicitly specify the format, or the special string <code>'iso-8601'</code>, which indicates that <a href="http://www.w3.org/TR/NOTE-datetime">ISO 8601</a> style times should be used. (eg <code>'12:34:56.000000'</code>)</p>
<p>Format strings may either be <a href="https://docs.python.org/3/library/datetime.html#strftime-and-strptime-behavior">Python strftime formats</a> which explicitly specify the format, or the special string <code>'iso-8601'</code>, which indicates that <a href="https://www.w3.org/TR/NOTE-datetime">ISO 8601</a> style times should be used. (eg <code>'12:34:56.000000'</code>)</p>
<h2 id="durationfield"><a class="toclink" href="#durationfield">DurationField</a></h2>
<p>A Duration representation.
Corresponds to <code>django.db.models.fields.DurationField</code></p>

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

@ -740,7 +740,7 @@ It's also recommended that you read the section on <a href="https://django-filte
filter_backends = (filters.DjangoObjectPermissionsFilter,)
permission_classes = (myapp.permissions.CustomObjectPermissions,)
</code></pre>
<p>For more information on adding <code>'view'</code> permissions for models, see the <a href="https://django-guardian.readthedocs.io/en/latest/userguide/assign.html">relevant section</a> of the <code>django-guardian</code> documentation, and <a href="http://blog.nyaruka.com/adding-a-view-permission-to-django-models">this blogpost</a>.</p>
<p>For more information on adding <code>'view'</code> permissions for models, see the <a href="https://django-guardian.readthedocs.io/en/latest/userguide/assign.html">relevant section</a> of the <code>django-guardian</code> documentation, and <a href="https://blog.nyaruka.com/adding-a-view-permission-to-django-models">this blogpost</a>.</p>
<hr />
<h1 id="custom-generic-filtering"><a class="toclink" href="#custom-generic-filtering">Custom generic filtering</a></h1>
<p>You can also provide your own generic filtering backend, or write an installable app for other developers to use.</p>

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

@ -438,7 +438,7 @@
<h1 id="metadata"><a class="toclink" href="#metadata">Metadata</a></h1>
<blockquote>
<p>[The <code>OPTIONS</code>] method allows a client to determine the options and/or requirements associated with a resource, or the capabilities of a server, without implying a resource action or initiating a resource retrieval.</p>
<p>&mdash; <a href="http://tools.ietf.org/html/rfc7231#section-4.3.7">RFC7231, Section 4.3.7.</a></p>
<p>&mdash; <a href="https://tools.ietf.org/html/rfc7231#section-4.3.7">RFC7231, Section 4.3.7.</a></p>
</blockquote>
<p>REST framework includes a configurable mechanism for determining how your API should respond to <code>OPTIONS</code> requests. This allows you to return API schema or other resource information.</p>
<p>There are not currently any widely adopted conventions for exactly what style of response should be returned for HTTP <code>OPTIONS</code> requests, so we provide an ad-hoc style that returns some useful information.</p>

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

@ -703,7 +703,7 @@ that REST framework provides, by implementing a <code>get_schema_fields()</code>
<h1 id="third-party-packages"><a class="toclink" href="#third-party-packages">Third party packages</a></h1>
<p>The following third party packages are also available.</p>
<h2 id="drf-extensions"><a class="toclink" href="#drf-extensions">DRF-extensions</a></h2>
<p>The <a href="http://chibisov.github.io/drf-extensions/docs/"><code>DRF-extensions</code> package</a> includes a <a href="http://chibisov.github.io/drf-extensions/docs/#paginatebymaxmixin"><code>PaginateByMaxMixin</code> mixin class</a> that allows your API clients to specify <code>?page_size=max</code> to obtain the maximum allowed page size.</p>
<p>The <a href="https://chibisov.github.io/drf-extensions/docs/"><code>DRF-extensions</code> package</a> includes a <a href="https://chibisov.github.io/drf-extensions/docs/#paginatebymaxmixin"><code>PaginateByMaxMixin</code> mixin class</a> that allows your API clients to specify <code>?page_size=max</code> to obtain the maximum allowed page size.</p>
<h2 id="drf-proxy-pagination"><a class="toclink" href="#drf-proxy-pagination">drf-proxy-pagination</a></h2>
<p>The <a href="https://github.com/tuffnatty/drf-proxy-pagination"><code>drf-proxy-pagination</code> package</a> includes a <code>ProxyPagination</code> class which allows to choose pagination class with a query parameter.</p>
<h2 id="link-header-pagination"><a class="toclink" href="#link-header-pagination">link-header-pagination</a></h2>

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

@ -494,7 +494,7 @@ sending more complex data than simple forms</p>
<hr />
<p><strong>Note</strong>: When developing client applications always remember to make sure you're setting the <code>Content-Type</code> header when sending data in an HTTP request.</p>
<p>If you don't set the content type, most clients will default to using <code>'application/x-www-form-urlencoded'</code>, which may not be what you wanted.</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>
<p>As an example, if you are sending <code>json</code> encoded data using jQuery with the <a href="https://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"><a class="toclink" href="#setting-the-parsers">Setting the parsers</a></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 only requests with <code>JSON</code> content, instead of the default of JSON or form data.</p>
@ -605,7 +605,7 @@ urlpatterns = [
<h1 id="third-party-packages"><a class="toclink" href="#third-party-packages">Third party packages</a></h1>
<p>The following third party packages are also available.</p>
<h2 id="yaml"><a class="toclink" href="#yaml">YAML</a></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>
<p><a href="https://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"><a class="toclink" href="#installation-configuration">Installation &amp; configuration</a></h4>
<p>Install using pip.</p>
<pre><code>$ pip install djangorestframework-yaml
@ -621,7 +621,7 @@ urlpatterns = [
}
</code></pre>
<h2 id="xml"><a class="toclink" href="#xml">XML</a></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>
<p><a href="https://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"><a class="toclink" href="#installation-configuration_1">Installation &amp; configuration</a></h4>
<p>Install using pip.</p>
<pre><code>$ pip install djangorestframework-xml

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

@ -519,7 +519,7 @@
<blockquote>
<p>Bad programmers worry about the code.
Good programmers worry about data structures and their relationships.</p>
<p>&mdash; <a href="http://lwn.net/Articles/193245/">Linus Torvalds</a></p>
<p>&mdash; <a href="https://lwn.net/Articles/193245/">Linus Torvalds</a></p>
</blockquote>
<p>Relational fields are used to represent model relationships. They can be applied to <code>ForeignKey</code>, <code>ManyToManyField</code> and <code>OneToOneField</code> relationships, as well as to reverse relationships, and custom relationships such as <code>GenericForeignKey</code>.</p>
<hr />

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

@ -796,7 +796,7 @@ In this case you can underspecify the media types it should respond to, by using
<h2 id="designing-your-media-types"><a class="toclink" href="#designing-your-media-types">Designing your media types</a></h2>
<p>For the purposes of many Web APIs, simple <code>JSON</code> responses with hyperlinked relations may be sufficient. If you want to fully embrace RESTful design and <a href="http://timelessrepo.com/haters-gonna-hateoas">HATEOAS</a> you'll need to consider the design and usage of your media types in more detail.</p>
<p>In <a href="http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven">the words of Roy Fielding</a>, "A REST API should spend almost all of its descriptive effort in defining the media type(s) used for representing resources and driving application state, or in defining extended relation names and/or hypertext-enabled mark-up for existing standard media types.".</p>
<p>For good examples of custom media types, see GitHub's use of a custom <a href="http://developer.github.com/v3/media/">application/vnd.github+json</a> media type, and Mike Amundsen's IANA approved <a href="http://www.amundsen.com/media-types/collection/">application/vnd.collection+json</a> JSON-based hypermedia.</p>
<p>For good examples of custom media types, see GitHub's use of a custom <a href="https://developer.github.com/v3/media/">application/vnd.github+json</a> media type, and Mike Amundsen's IANA approved <a href="http://www.amundsen.com/media-types/collection/">application/vnd.collection+json</a> JSON-based hypermedia.</p>
<h2 id="html-error-views"><a class="toclink" href="#html-error-views">HTML error views</a></h2>
<p>Typically a renderer will behave the same regardless of if it's dealing with a regular response, or with a response caused by an exception being raised, such as an <code>Http404</code> or <code>PermissionDenied</code> exception, or a subclass of <code>APIException</code>.</p>
<p>If you're using either the <code>TemplateHTMLRenderer</code> or the <code>StaticHTMLRenderer</code> and an exception is raised, the behavior is slightly different, and mirrors <a href="https://docs.djangoproject.com/en/stable/topics/http/views/#customizing-error-views">Django's default handling of error views</a>.</p>
@ -812,7 +812,7 @@ In this case you can underspecify the media types it should respond to, by using
<h1 id="third-party-packages"><a class="toclink" href="#third-party-packages">Third party packages</a></h1>
<p>The following third party packages are also available.</p>
<h2 id="yaml"><a class="toclink" href="#yaml">YAML</a></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>
<p><a href="https://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"><a class="toclink" href="#installation-configuration">Installation &amp; configuration</a></h4>
<p>Install using pip.</p>
<pre><code>$ pip install djangorestframework-yaml
@ -828,7 +828,7 @@ In this case you can underspecify the media types it should respond to, by using
}
</code></pre>
<h2 id="xml"><a class="toclink" href="#xml">XML</a></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>
<p><a href="https://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"><a class="toclink" href="#installation-configuration_1">Installation &amp; configuration</a></h4>
<p>Install using pip.</p>
<pre><code>$ pip install djangorestframework-xml
@ -844,10 +844,10 @@ In this case you can underspecify the media types it should respond to, by using
}
</code></pre>
<h2 id="jsonp"><a class="toclink" href="#jsonp">JSONP</a></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>
<p><a href="https://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>
<p><strong>Warning</strong>: If you require cross-domain AJAX requests, you should generally be using the more modern approach of <a href="https://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="https://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"><a class="toclink" href="#installation-configuration_2">Installation &amp; configuration</a></h4>
<p>Install using pip.</p>
@ -861,7 +861,7 @@ In this case you can underspecify the media types it should respond to, by using
}
</code></pre>
<h2 id="messagepack"><a class="toclink" href="#messagepack">MessagePack</a></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>
<p><a href="https://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"><a class="toclink" href="#csv">CSV</a></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>
<h2 id="ultrajson"><a class="toclink" href="#ultrajson">UltraJSON</a></h2>
@ -869,7 +869,7 @@ In this case you can underspecify the media types it should respond to, by using
<h2 id="camelcase-json"><a class="toclink" href="#camelcase-json">CamelCase JSON</a></h2>
<p><a href="https://github.com/vbabiy/djangorestframework-camel-case">djangorestframework-camel-case</a> provides camel case JSON renderers and parsers for REST framework. This allows serializers to use Python-style underscored field names, but be exposed in the API as Javascript-style camel case field names. It is maintained by <a href="https://github.com/vbabiy">Vitaly Babiy</a>.</p>
<h2 id="pandas-csv-excel-png"><a class="toclink" href="#pandas-csv-excel-png">Pandas (CSV, Excel, PNG)</a></h2>
<p><a href="https://github.com/wq/django-rest-pandas">Django REST Pandas</a> provides a serializer and renderers that support additional data processing and output via the <a href="http://pandas.pydata.org/">Pandas</a> DataFrame API. Django REST Pandas includes renderers for Pandas-style CSV files, Excel workbooks (both <code>.xls</code> and <code>.xlsx</code>), and a number of <a href="https://github.com/wq/django-rest-pandas#supported-formats">other formats</a>. It is maintained by <a href="https://github.com/sheppard">S. Andrew Sheppard</a> as part of the <a href="https://github.com/wq">wq Project</a>.</p>
<p><a href="https://github.com/wq/django-rest-pandas">Django REST Pandas</a> provides a serializer and renderers that support additional data processing and output via the <a href="https://pandas.pydata.org/">Pandas</a> DataFrame API. Django REST Pandas includes renderers for Pandas-style CSV files, Excel workbooks (both <code>.xls</code> and <code>.xlsx</code>), and a number of <a href="https://github.com/wq/django-rest-pandas#supported-formats">other formats</a>. It is maintained by <a href="https://github.com/sheppard">S. Andrew Sheppard</a> as part of the <a href="https://github.com/wq">wq Project</a>.</p>
<h2 id="latex"><a class="toclink" href="#latex">LaTeX</a></h2>
<p><a href="https://github.com/mypebble/rest-framework-latex">Rest Framework Latex</a> provides a renderer that outputs PDFs using Laulatex. It is maintained by <a href="https://github.com/mypebble">Pebble (S/F Software)</a>.</p>

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

@ -418,7 +418,7 @@
<h1 id="returning-urls"><a class="toclink" href="#returning-urls">Returning URLs</a></h1>
<blockquote>
<p>The central feature that distinguishes the REST architectural style from other network-based styles is its emphasis on a uniform interface between components.</p>
<p>&mdash; Roy Fielding, <a href="http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_1_5">Architectural Styles and the Design of Network-based Software Architectures</a></p>
<p>&mdash; Roy Fielding, <a href="https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_1_5">Architectural Styles and the Design of Network-based Software Architectures</a></p>
</blockquote>
<p>As a rule, it's probably better practice to return absolute URIs from your Web APIs, such as <code>http://example.com/foobar</code>, rather than returning relative URIs, such as <code>/foobar</code>.</p>
<p>The advantages of doing so are:</p>

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

@ -713,14 +713,14 @@ urlpatterns = router.urls
<h2 id="drf-nested-routers"><a class="toclink" href="#drf-nested-routers">DRF Nested Routers</a></h2>
<p>The <a href="https://github.com/alanjds/drf-nested-routers">drf-nested-routers package</a> provides routers and relationship fields for working with nested resources.</p>
<h2 id="modelrouter-wqdbrest"><a class="toclink" href="#modelrouter-wqdbrest">ModelRouter (wq.db.rest)</a></h2>
<p>The <a href="http://wq.io/wq.db">wq.db package</a> provides an advanced <a href="http://wq.io/docs/router">ModelRouter</a> class (and singleton instance) that extends <code>DefaultRouter</code> with a <code>register_model()</code> API. Much like Django's <code>admin.site.register</code>, the only required argument to <code>rest.router.register_model</code> is a model class. Reasonable defaults for a url prefix, serializer, and viewset will be inferred from the model and global configuration.</p>
<p>The <a href="https://wq.io/wq.db">wq.db package</a> provides an advanced <a href="https://wq.io/docs/router">ModelRouter</a> class (and singleton instance) that extends <code>DefaultRouter</code> with a <code>register_model()</code> API. Much like Django's <code>admin.site.register</code>, the only required argument to <code>rest.router.register_model</code> is a model class. Reasonable defaults for a url prefix, serializer, and viewset will be inferred from the model and global configuration.</p>
<pre><code>from wq.db import rest
from myapp.models import MyModel
rest.router.register_model(MyModel)
</code></pre>
<h2 id="drf-extensions"><a class="toclink" href="#drf-extensions">DRF-extensions</a></h2>
<p>The <a href="http://chibisov.github.io/drf-extensions/docs/"><code>DRF-extensions</code> package</a> provides <a href="http://chibisov.github.io/drf-extensions/docs/#routers">routers</a> for creating <a href="http://chibisov.github.io/drf-extensions/docs/#nested-routes">nested viewsets</a>, <a href="http://chibisov.github.io/drf-extensions/docs/#collection-level-controllers">collection level controllers</a> with <a href="http://chibisov.github.io/drf-extensions/docs/#controller-endpoint-name">customizable endpoint names</a>.</p>
<p>The <a href="https://chibisov.github.io/drf-extensions/docs/"><code>DRF-extensions</code> package</a> provides <a href="https://chibisov.github.io/drf-extensions/docs/#routers">routers</a> for creating <a href="https://chibisov.github.io/drf-extensions/docs/#nested-routes">nested viewsets</a>, <a href="https://chibisov.github.io/drf-extensions/docs/#collection-level-controllers">collection level controllers</a> with <a href="https://chibisov.github.io/drf-extensions/docs/#controller-endpoint-name">customizable endpoint names</a>.</p>
</div> <!--/span-->

7
api-guide/schemas/index.html
View File

@ -480,6 +480,10 @@
</li>
<li>
<a href="#drf-yasg-yet-another-swagger-generator">drf-yasg - Yet Another Swagger Generator</a>
</li>
<li>
<a href="#drf-openapi">DRF OpenAPI</a>
</li>
@ -1120,6 +1124,9 @@ Valid only if a <code>location="body"</code> field is included on the <code>Link
<p>A short description of the meaning and intended usage of the input field.</p>
<hr />
<h1 id="third-party-packages"><a class="toclink" href="#third-party-packages">Third party packages</a></h1>
<h2 id="drf-yasg-yet-another-swagger-generator"><a class="toclink" href="#drf-yasg-yet-another-swagger-generator">drf-yasg - Yet Another Swagger Generator</a></h2>
<p><a href="https://github.com/axnsan12/drf-yasg/">drf-yasg</a> generates <a href="https://openapis.org/">OpenAPI</a> documents suitable for code generation - nested schemas,
named models, response bodies, enum/pattern/min/max validators, form parameters, etc.</p>
<h2 id="drf-openapi"><a class="toclink" href="#drf-openapi">DRF OpenAPI</a></h2>
<p><a href="https://github.com/limdauto/drf_openapi">DRF OpenAPI</a> renders the schema generated by Django Rest Framework
in <a href="https://openapis.org/">OpenAPI</a> format.</p>

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

@ -904,7 +904,7 @@ serializer.errors
return instance
</code></pre>
<p>Because the behavior of nested creates and updates can be ambiguous, and may require complex dependencies between related models, REST framework 3 requires you to always write these methods explicitly. The default <code>ModelSerializer</code> <code>.create()</code> and <code>.update()</code> methods do not include support for writable nested representations.</p>
<p>It is possible that a third party package, providing automatic support some kinds of automatic writable nested representations may be released alongside the 3.1 release.</p>
<p>There are however, third-party packages available such as <a href="./#drf-writable-nested">DRF Writable Nested</a> that support automatic writable nested representations.</p>
<h4 id="handling-saving-related-instances-in-model-manager-classes"><a class="toclink" href="#handling-saving-related-instances-in-model-manager-classes">Handling saving related instances in model manager classes</a></h4>
<p>An alternative to saving multiple related instances in the serializer is to write custom model manager classes that handle creating the correct instances.</p>
<p>For example, suppose we wanted to ensure that <code>User</code> instances and <code>Profile</code> instances are always created together as a pair. We might write a custom manager class that looks something like this:</p>
@ -931,7 +931,7 @@ serializer.errors
has_support_contract=validated_data['profile']['has_support_contract']
)
</code></pre>
<p>For more details on this approach see the Django documentation on <a href="https://docs.djangoproject.com/en/stable/topics/db/managers/">model managers</a>, and <a href="http://www.dabapps.com/blog/django-models-and-encapsulation/">this blogpost on using model and manager classes</a>.</p>
<p>For more details on this approach see the Django documentation on <a href="https://docs.djangoproject.com/en/stable/topics/db/managers/">model managers</a>, and <a href="https://www.dabapps.com/blog/django-models-and-encapsulation/">this blogpost on using model and manager classes</a>.</p>
<h2 id="dealing-with-multiple-objects"><a class="toclink" href="#dealing-with-multiple-objects">Dealing with multiple objects</a></h2>
<p>The <code>Serializer</code> class can also handle serializing or deserializing lists of objects.</p>
<h4 id="serializing-multiple-objects"><a class="toclink" href="#serializing-multiple-objects">Serializing multiple objects</a></h4>
@ -1456,7 +1456,7 @@ class MySerializer(MyBaseSerializer):
if fields is not None:
# Drop any fields that are not specified in the `fields` argument.
allowed = set(fields)
existing = set(self.fields.keys())
existing = set(self.fields)
for field_name in existing - allowed:
self.fields.pop(field_name)
</code></pre>
@ -1480,7 +1480,7 @@ class MySerializer(MyBaseSerializer):
<h1 id="third-party-packages"><a class="toclink" href="#third-party-packages">Third party packages</a></h1>
<p>The following third party packages are also available.</p>
<h2 id="django-rest-marshmallow"><a class="toclink" href="#django-rest-marshmallow">Django REST marshmallow</a></h2>
<p>The <a href="http://tomchristie.github.io/django-rest-marshmallow/">django-rest-marshmallow</a> package provides an alternative implementation for serializers, using the python <a href="https://marshmallow.readthedocs.io/en/latest/">marshmallow</a> library. It exposes the same API as the REST framework serializers, and can be used as a drop-in replacement in some use-cases.</p>
<p>The <a href="https://tomchristie.github.io/django-rest-marshmallow/">django-rest-marshmallow</a> package provides an alternative implementation for serializers, using the python <a href="https://marshmallow.readthedocs.io/en/latest/">marshmallow</a> library. It exposes the same API as the REST framework serializers, and can be used as a drop-in replacement in some use-cases.</p>
<h2 id="serpy"><a class="toclink" href="#serpy">Serpy</a></h2>
<p>The <a href="https://github.com/clarkduvall/serpy">serpy</a> package is an alternative implementation for serializers that is built for speed. <a href="https://github.com/clarkduvall/serpy">Serpy</a> serializes complex datatypes to simple native types. The native types can be easily converted to JSON or any other format needed.</p>
<h2 id="mongoenginemodelserializer"><a class="toclink" href="#mongoenginemodelserializer">MongoengineModelSerializer</a></h2>
@ -1505,9 +1505,9 @@ blacklisted and child serializers can be optionally expanded.</p>
<h2 id="drf-base64"><a class="toclink" href="#drf-base64">DRF-Base64</a></h2>
<p><a href="https://bitbucket.org/levit_scs/drf_base64">DRF-Base64</a> provides a set of field and model serializers that handles the upload of base64-encoded files.</p>
<h2 id="queryfields"><a class="toclink" href="#queryfields">QueryFields</a></h2>
<p><a href="http://djangorestframework-queryfields.readthedocs.io/">djangorestframework-queryfields</a> allows API clients to specify which fields will be sent in the response via inclusion/exclusion query parameters.</p>
<p><a href="https://djangorestframework-queryfields.readthedocs.io/">djangorestframework-queryfields</a> allows API clients to specify which fields will be sent in the response via inclusion/exclusion query parameters.</p>
<h2 id="drf-writable-nested"><a class="toclink" href="#drf-writable-nested">DRF Writable Nested</a></h2>
<p>The <a href="http://github.com/beda-software/drf-writable-nested">drf-writable-nested</a> package provides writable nested model serializer which allows to create/update models with nested related data.</p>
<p>The <a href="https://github.com/beda-software/drf-writable-nested">drf-writable-nested</a> package provides writable nested model serializer which allows to create/update models with nested related data.</p>
</div> <!--/span-->

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

@ -670,7 +670,7 @@ internally in the codebase.</p>
<p>When set to <code>False</code>, JSON responses will escape non-ascii characters, like so:</p>
<pre><code>{"unicode black star":"\u2605"}
</code></pre>
<p>Both styles conform to <a href="http://www.ietf.org/rfc/rfc4627.txt">RFC 4627</a>, and are syntactically valid JSON. The unicode style is preferred as being more user-friendly when inspecting API responses.</p>
<p>Both styles conform to <a href="https://www.ietf.org/rfc/rfc4627.txt">RFC 4627</a>, and are syntactically valid JSON. The unicode style is preferred as being more user-friendly when inspecting API responses.</p>
<p>Default: <code>True</code></p>
<h4 id="compact_json"><a class="toclink" href="#compact_json">COMPACT_JSON</a></h4>
<p>When set to <code>True</code>, JSON responses will return compact representations, with no spacing after <code>':'</code> and <code>','</code> characters. For example:</p>

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

@ -434,7 +434,7 @@
<h1 id="status-codes"><a class="toclink" href="#status-codes">Status Codes</a></h1>
<blockquote>
<p>418 I'm a teapot - Any attempt to brew coffee with a teapot should result in the error code "418 I'm a teapot". The resulting entity body MAY be short and stout.</p>
<p>&mdash; <a href="http://www.ietf.org/rfc/rfc2324.txt">RFC 2324</a>, Hyper Text Coffee Pot Control Protocol</p>
<p>&mdash; <a href="https://www.ietf.org/rfc/rfc2324.txt">RFC 2324</a>, Hyper Text Coffee Pot Control Protocol</p>
</blockquote>
<p>Using bare status codes in your responses isn't recommended. REST framework includes a set of named constants that you can use to make your code more obvious and readable.</p>
<pre><code>from rest_framework import status
@ -455,8 +455,8 @@ class ExampleTestCase(APITestCase):
response = self.client.get(url)
self.assertTrue(status.is_success(response.status_code))
</code></pre>
<p>For more information on proper usage of HTTP status codes see <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html">RFC 2616</a>
and <a href="http://tools.ietf.org/html/rfc6585">RFC 6585</a>.</p>
<p>For more information on proper usage of HTTP status codes see <a href="https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html">RFC 2616</a>
and <a href="https://tools.ietf.org/html/rfc6585">RFC 6585</a>.</p>
<h2 id="informational-1xx"><a class="toclink" href="#informational-1xx">Informational - 1xx</a></h2>
<p>This class of status code indicates a provisional response. There are no 1xx status codes used in REST framework by default.</p>
<pre><code>HTTP_100_CONTINUE

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

@ -456,7 +456,7 @@
<li class="main">
<a href="#test-cases">Test cases</a>
<a href="#api-test-cases">API Test cases</a>
</li>
@ -465,6 +465,16 @@
</li>
<li class="main">
<a href="#urlpatternstestcase">URLPatternsTestCase</a>
</li>
<li>
<a href="#example_1">Example</a>
</li>
<li class="main">
<a href="#testing-responses">Testing responses</a>
</li>
@ -516,7 +526,7 @@
<h1 id="testing"><a class="toclink" href="#testing">Testing</a></h1>
<blockquote>
<p>Code without tests is broken as designed.</p>
<p>&mdash; <a href="http://jacobian.org/writing/django-apps-with-buildout/#s-create-a-test-wrapper">Jacob Kaplan-Moss</a></p>
<p>&mdash; <a href="https://jacobian.org/writing/django-apps-with-buildout/#s-create-a-test-wrapper">Jacob Kaplan-Moss</a></p>
</blockquote>
<p>REST framework includes a few helper classes that extend Django's existing test framework, and improve support for making API requests.</p>
<h1 id="apirequestfactory"><a class="toclink" href="#apirequestfactory">APIRequestFactory</a></h1>
@ -730,7 +740,7 @@ client.session.auth = HTTPBasicAuth('user', 'pass')
client.session.headers.update({'x-test': 'true'})
</code></pre>
<hr />
<h1 id="test-cases"><a class="toclink" href="#test-cases">Test cases</a></h1>
<h1 id="api-test-cases"><a class="toclink" href="#api-test-cases">API Test cases</a></h1>
<p>REST framework includes the following test case classes, that mirror the existing Django test case classes, but use <code>APIClient</code> instead of Django's default <code>Client</code>.</p>
<ul>
<li><code>APISimpleTestCase</code></li>
@ -758,6 +768,28 @@ class AccountTests(APITestCase):
self.assertEqual(Account.objects.get().name, 'DabApps')
</code></pre>
<hr />
<h1 id="urlpatternstestcase"><a class="toclink" href="#urlpatternstestcase">URLPatternsTestCase</a></h1>
<p>REST framework also provides a test case class for isolating <code>urlpatterns</code> on a per-class basis. Note that this inherits from Django's <code>SimpleTestCase</code>, and will most likely need to be mixed with another test case class.</p>
<h2 id="example_1"><a class="toclink" href="#example_1">Example</a></h2>
<pre><code>from django.urls import include, path, reverse
from rest_framework.test import APITestCase, URLPatternsTestCase
class AccountTests(APITestCase, URLPatternsTestCase):
urlpatterns = [
path('api/', include('api.urls')),
]
def test_create_account(self):
"""
Ensure we can create a new account object.
"""
url = reverse('account-list')
response = self.client.get(url, format='json')
self.assertEqual(response.status_code, status.HTTP_200_OK)
self.assertEqual(len(response.data), 1)
</code></pre>
<hr />
<h1 id="testing-responses"><a class="toclink" href="#testing-responses">Testing responses</a></h1>
<h2 id="checking-the-response-data"><a class="toclink" href="#checking-the-response-data">Checking the response data</a></h2>
<p>When checking the validity of test responses it's often more convenient to inspect the data that the response was created with, rather than inspecting the fully rendered response.</p>

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

@ -506,7 +506,7 @@ def example_view(request, format=None):
<h2 id="how-clients-are-identified"><a class="toclink" href="#how-clients-are-identified">How clients are identified</a></h2>
<p>The <code>X-Forwarded-For</code> HTTP header and <code>REMOTE_ADDR</code> WSGI variable are used to uniquely identify client IP addresses for throttling. If the <code>X-Forwarded-For</code> header is present then it will be used, otherwise the value of the <code>REMOTE_ADDR</code> variable from the WSGI environment will be used.</p>
<p>If you need to strictly identify unique client IP addresses, you'll need to first configure the number of application proxies that the API runs behind by setting the <code>NUM_PROXIES</code> setting. This setting should be an integer of zero or more. If set to non-zero then the client IP will be identified as being the last IP address in the <code>X-Forwarded-For</code> header, once any application proxy IP addresses have first been excluded. If set to zero, then the <code>REMOTE_ADDR</code> value will always be used as the identifying IP address.</p>
<p>It is important to understand that if you configure the <code>NUM_PROXIES</code> setting, then all clients behind a unique <a href="http://en.wikipedia.org/wiki/Network_address_translation">NAT'd</a> gateway will be treated as a single client.</p>
<p>It is important to understand that if you configure the <code>NUM_PROXIES</code> setting, then all clients behind a unique <a href="https://en.wikipedia.org/wiki/Network_address_translation">NAT'd</a> gateway will be treated as a single client.</p>
<p>Further context on how the <code>X-Forwarded-For</code> header works, and identifying a remote client IP can be <a href="http://oxpedia.org/wiki/index.php?title=AppSuite:Grizzly#Multiple_Proxies_in_front_of_the_cluster">found here</a>.</p>
<h2 id="setting-up-the-cache"><a class="toclink" href="#setting-up-the-cache">Setting up the cache</a></h2>
<p>The throttle classes provided by REST framework use Django's cache backend. You should make sure that you've set appropriate <a href="https://docs.djangoproject.com/en/stable/ref/settings/#caches">cache settings</a>. The default value of <code>LocMemCache</code> backend should be okay for simple setups. See Django's <a href="https://docs.djangoproject.com/en/stable/topics/cache/#setting-up-the-cache">cache documentation</a> for more details.</p>

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

@ -454,11 +454,11 @@
<h1 id="versioning"><a class="toclink" href="#versioning">Versioning</a></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>
<p>&mdash; <a href="https://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>
<p>There are a number of valid approaches to approaching versioning. <a href="https://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"><a class="toclink" href="#versioning-with-rest-framework">Versioning with REST framework</a></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>
@ -530,7 +530,7 @@ Accept: application/json; version=1.0
<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/blob/master/en/foundations/require-versioning-in-the-accepts-header.md">best practice</a>, although other styles may be suitable depending on your client requirements.</p>
<h4 id="using-accept-headers-with-vendor-media-types"><a class="toclink" href="#using-accept-headers-with-vendor-media-types">Using accept headers with vendor media types</a></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>
<p>Strictly speaking the <code>json</code> media type is not specified as <a href="https://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="https://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>
@ -591,7 +591,7 @@ Accept: application/json
<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>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 tutorials on how 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"><a class="toclink" href="#queryparameterversioning">QueryParameterVersioning</a></h2>
<p>This scheme is a simple style that includes the version as a query parameter in the URL. For example:</p>

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

@ -448,7 +448,7 @@
<h1 id="class-based-views"><a class="toclink" href="#class-based-views">Class-based Views</a></h1>
<blockquote>
<p>Django's class-based views are a welcome departure from the old-style views.</p>
<p>&mdash; <a href="http://reinout.vanrees.org/weblog/2011/08/24/class-based-views-usage.html">Reinout van Rees</a></p>
<p>&mdash; <a href="https://reinout.vanrees.org/weblog/2011/08/24/class-based-views-usage.html">Reinout van Rees</a></p>
</blockquote>
<p>REST framework provides an <code>APIView</code> class, which subclasses Django's <code>View</code> class.</p>
<p><code>APIView</code> classes are different from regular <code>View</code> classes in the following ways:</p>

BIN
img/drf-yasg.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 58 KiB

20
index.html
View File

@ -491,9 +491,9 @@
</style>
<p class="badges" height=20px>
<iframe src="http://ghbtns.com/github-btn.html?user=encode&amp;repo=django-rest-framework&amp;type=watch&amp;count=true" class="github-star-button" allowtransparency="true" frameborder="0" scrolling="0" width="110px" height="20px"></iframe>
<iframe src="https://ghbtns.com/github-btn.html?user=encode&amp;repo=django-rest-framework&amp;type=watch&amp;count=true" class="github-star-button" allowtransparency="true" frameborder="0" scrolling="0" width="110px" height="20px"></iframe>
<a href="http://travis-ci.org/encode/django-rest-framework?branch=master">
<a href="https://travis-ci.org/encode/django-rest-framework?branch=master">
<img src="https://secure.travis-ci.org/encode/django-rest-framework.svg?branch=master" class="status-badge">
</a>
@ -503,7 +503,7 @@
</p>
<hr />
<p><strong>Note</strong>: This is the documentation for the <strong>version 3</strong> of REST framework. Documentation for <a href="http://tomchristie.github.io/rest-framework-2-docs/">version 2</a> is also available.</p>
<p><strong>Note</strong>: This is the documentation for the <strong>version 3</strong> of REST framework. Documentation for <a href="https://tomchristie.github.io/rest-framework-2-docs/">version 2</a> is also available.</p>
<hr />
<p>
<h1 style="position: absolute;
@ -521,12 +521,12 @@
<p>Django REST framework is a powerful and flexible toolkit for building Web APIs.</p>
<p>Some reasons you might want to use REST framework:</p>
<ul>
<li>The <a href="http://restframework.herokuapp.com/">Web browsable API</a> is a huge usability win for your developers.</li>
<li>The <a href="https://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 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>
<li>Used and trusted by internationally recognised companies including <a href="http://www.mozilla.org/en-US/about/">Mozilla</a>, <a href="https://www.redhat.com/">Red Hat</a>, <a href="https://www.heroku.com/">Heroku</a>, and <a href="https://www.eventbrite.co.uk/about/">Eventbrite</a>.</li>
<li>Used and trusted by internationally recognised companies including <a href="https://www.mozilla.org/en-US/about/">Mozilla</a>, <a href="https://www.redhat.com/">Red Hat</a>, <a href="https://www.heroku.com/">Heroku</a>, and <a href="https://www.eventbrite.co.uk/about/">Eventbrite</a>.</li>
</ul>
<hr />
<h2 id="funding"><a class="toclink" href="#funding">Funding</a></h2>
@ -554,9 +554,9 @@ continued development by <strong><a href="topics/funding/">signing up for a paid
</ul>
<p>The following packages are optional:</p>
<ul>
<li><a href="http://pypi.python.org/pypi/coreapi/">coreapi</a> (1.32.0+) - Schema generation support.</li>
<li><a href="http://pypi.python.org/pypi/Markdown/">Markdown</a> (2.1.0+) - Markdown support for the browsable API.</li>
<li><a href="http://pypi.python.org/pypi/django-filter">django-filter</a> (1.0.1+) - Filtering support.</li>
<li><a href="https://pypi.python.org/pypi/coreapi/">coreapi</a> (1.32.0+) - Schema generation support.</li>
<li><a href="https://pypi.python.org/pypi/Markdown/">Markdown</a> (2.1.0+) - Markdown support for the browsable API.</li>
<li><a href="https://pypi.python.org/pypi/django-filter">django-filter</a> (1.0.1+) - Filtering support.</li>
<li><a href="https://github.com/maraujop/django-crispy-forms">django-crispy-forms</a> - Improved HTML display for filtering.</li>
<li><a href="https://github.com/django-guardian/django-guardian">django-guardian</a> (1.1.1+) - Object level permissions support.</li>
</ul>
@ -637,7 +637,7 @@ urlpatterns = [
<li><a href="tutorial/6-viewsets-and-routers/">6 - Viewsets &amp; routers</a></li>
<li><a href="tutorial/7-schemas-and-client-libraries/">7 - Schemas &amp; client libraries</a></li>
</ul>
<p>There is a live example API of the finished tutorial API for testing purposes, <a href="http://restframework.herokuapp.com/">available here</a>.</p>
<p>There is a live example API of the finished tutorial API for testing purposes, <a href="https://restframework.herokuapp.com/">available here</a>.</p>
<h2 id="api-guide"><a class="toclink" href="#api-guide">API Guide</a></h2>
<p>The API guide is your complete reference manual to all the functionality provided by REST framework.</p>
<ul>
@ -703,7 +703,7 @@ urlpatterns = [
the repository, run the test suite and contribute changes back to REST
Framework.</p>
<h2 id="support"><a class="toclink" href="#support">Support</a></h2>
<p>For support please see the <a href="https://groups.google.com/forum/?fromgroups#!forum/django-rest-framework">REST framework discussion group</a>, try the <code>#restframework</code> channel on <code>irc.freenode.net</code>, search <a href="https://botbot.me/freenode/restframework/">the IRC archives</a>, or raise a question on <a href="http://stackoverflow.com/">Stack Overflow</a>, making sure to include the <a href="http://stackoverflow.com/questions/tagged/django-rest-framework">'django-rest-framework'</a> tag.</p>
<p>For support please see the <a href="https://groups.google.com/forum/?fromgroups#!forum/django-rest-framework">REST framework discussion group</a>, try the <code>#restframework</code> channel on <code>irc.freenode.net</code>, search <a href="https://botbot.me/freenode/restframework/">the IRC archives</a>, or raise a question on <a href="https://stackoverflow.com/">Stack Overflow</a>, making sure to include the <a href="https://stackoverflow.com/questions/tagged/django-rest-framework">'django-rest-framework'</a> tag.</p>
<p>For priority support please sign up for a <a href="https://fund.django-rest-framework.org/topics/funding/">professional or premium sponsorship plan</a>.</p>
<p>For updates on REST framework development, you may also want to follow <a href="https://twitter.com/_tomchristie">the author</a> on Twitter.</p>
<p><a style="padding-top: 10px" href="https://twitter.com/_tomchristie" class="twitter-follow-button" data-show-count="false">Follow @_tomchristie</a>

60
mkdocs/search_index.json
View File

File diff suppressed because one or more lines are too long

122
sitemap.xml
View File

@ -4,7 +4,7 @@
<url>
<loc>http://www.django-rest-framework.org//</loc>
<lastmod>2017-12-22</lastmod>
<lastmod>2018-01-15</lastmod>
<changefreq>daily</changefreq>
</url>
@ -13,49 +13,49 @@
<url>
<loc>http://www.django-rest-framework.org//tutorial/quickstart/</loc>
<lastmod>2017-12-22</lastmod>
<lastmod>2018-01-15</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//tutorial/1-serialization/</loc>
<lastmod>2017-12-22</lastmod>
<lastmod>2018-01-15</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//tutorial/2-requests-and-responses/</loc>
<lastmod>2017-12-22</lastmod>
<lastmod>2018-01-15</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//tutorial/3-class-based-views/</loc>
<lastmod>2017-12-22</lastmod>
<lastmod>2018-01-15</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//tutorial/4-authentication-and-permissions/</loc>
<lastmod>2017-12-22</lastmod>
<lastmod>2018-01-15</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//tutorial/5-relationships-and-hyperlinked-apis/</loc>
<lastmod>2017-12-22</lastmod>
<lastmod>2018-01-15</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//tutorial/6-viewsets-and-routers/</loc>
<lastmod>2017-12-22</lastmod>
<lastmod>2018-01-15</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//tutorial/7-schemas-and-client-libraries/</loc>
<lastmod>2017-12-22</lastmod>
<lastmod>2018-01-15</lastmod>
<changefreq>daily</changefreq>
</url>
@ -65,163 +65,163 @@
<url>
<loc>http://www.django-rest-framework.org//api-guide/requests/</loc>
<lastmod>2017-12-22</lastmod>
<lastmod>2018-01-15</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//api-guide/responses/</loc>
<lastmod>2017-12-22</lastmod>
<lastmod>2018-01-15</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//api-guide/views/</loc>
<lastmod>2017-12-22</lastmod>
<lastmod>2018-01-15</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//api-guide/generic-views/</loc>
<lastmod>2017-12-22</lastmod>
<lastmod>2018-01-15</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//api-guide/viewsets/</loc>
<lastmod>2017-12-22</lastmod>
<lastmod>2018-01-15</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//api-guide/routers/</loc>
<lastmod>2017-12-22</lastmod>
<lastmod>2018-01-15</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//api-guide/parsers/</loc>
<lastmod>2017-12-22</lastmod>
<lastmod>2018-01-15</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//api-guide/renderers/</loc>
<lastmod>2017-12-22</lastmod>
<lastmod>2018-01-15</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//api-guide/serializers/</loc>
<lastmod>2017-12-22</lastmod>
<lastmod>2018-01-15</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//api-guide/fields/</loc>
<lastmod>2017-12-22</lastmod>
<lastmod>2018-01-15</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//api-guide/relations/</loc>
<lastmod>2017-12-22</lastmod>
<lastmod>2018-01-15</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//api-guide/validators/</loc>
<lastmod>2017-12-22</lastmod>
<lastmod>2018-01-15</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//api-guide/authentication/</loc>
<lastmod>2017-12-22</lastmod>
<lastmod>2018-01-15</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//api-guide/permissions/</loc>
<lastmod>2017-12-22</lastmod>
<lastmod>2018-01-15</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//api-guide/throttling/</loc>
<lastmod>2017-12-22</lastmod>
<lastmod>2018-01-15</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//api-guide/filtering/</loc>
<lastmod>2017-12-22</lastmod>
<lastmod>2018-01-15</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//api-guide/pagination/</loc>
<lastmod>2017-12-22</lastmod>
<lastmod>2018-01-15</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//api-guide/versioning/</loc>
<lastmod>2017-12-22</lastmod>
<lastmod>2018-01-15</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//api-guide/content-negotiation/</loc>
<lastmod>2017-12-22</lastmod>
<lastmod>2018-01-15</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//api-guide/metadata/</loc>
<lastmod>2017-12-22</lastmod>
<lastmod>2018-01-15</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//api-guide/schemas/</loc>
<lastmod>2017-12-22</lastmod>
<lastmod>2018-01-15</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//api-guide/format-suffixes/</loc>
<lastmod>2017-12-22</lastmod>
<lastmod>2018-01-15</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//api-guide/reverse/</loc>
<lastmod>2017-12-22</lastmod>
<lastmod>2018-01-15</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//api-guide/exceptions/</loc>
<lastmod>2017-12-22</lastmod>
<lastmod>2018-01-15</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//api-guide/status-codes/</loc>
<lastmod>2017-12-22</lastmod>
<lastmod>2018-01-15</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//api-guide/testing/</loc>
<lastmod>2017-12-22</lastmod>
<lastmod>2018-01-15</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//api-guide/settings/</loc>
<lastmod>2017-12-22</lastmod>
<lastmod>2018-01-15</lastmod>
<changefreq>daily</changefreq>
</url>
@ -231,151 +231,151 @@
<url>
<loc>http://www.django-rest-framework.org//topics/documenting-your-api/</loc>
<lastmod>2017-12-22</lastmod>
<lastmod>2018-01-15</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//topics/api-clients/</loc>
<lastmod>2017-12-22</lastmod>
<lastmod>2018-01-15</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//topics/internationalization/</loc>
<lastmod>2017-12-22</lastmod>
<lastmod>2018-01-15</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//topics/ajax-csrf-cors/</loc>
<lastmod>2017-12-22</lastmod>
<lastmod>2018-01-15</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//topics/html-and-forms/</loc>
<lastmod>2017-12-22</lastmod>
<lastmod>2018-01-15</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//topics/browser-enhancements/</loc>
<lastmod>2017-12-22</lastmod>
<lastmod>2018-01-15</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//topics/browsable-api/</loc>
<lastmod>2017-12-22</lastmod>
<lastmod>2018-01-15</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//topics/rest-hypermedia-hateoas/</loc>
<lastmod>2017-12-22</lastmod>
<lastmod>2018-01-15</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//topics/third-party-packages/</loc>
<lastmod>2017-12-22</lastmod>
<lastmod>2018-01-15</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//topics/tutorials-and-resources/</loc>
<lastmod>2017-12-22</lastmod>
<lastmod>2018-01-15</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//topics/contributing/</loc>
<lastmod>2017-12-22</lastmod>
<lastmod>2018-01-15</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//topics/project-management/</loc>
<lastmod>2017-12-22</lastmod>
<lastmod>2018-01-15</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//topics/jobs/</loc>
<lastmod>2017-12-22</lastmod>
<lastmod>2018-01-15</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//topics/3.0-announcement/</loc>
<lastmod>2017-12-22</lastmod>
<lastmod>2018-01-15</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//topics/3.1-announcement/</loc>
<lastmod>2017-12-22</lastmod>
<lastmod>2018-01-15</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//topics/3.2-announcement/</loc>
<lastmod>2017-12-22</lastmod>
<lastmod>2018-01-15</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//topics/3.3-announcement/</loc>
<lastmod>2017-12-22</lastmod>
<lastmod>2018-01-15</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//topics/3.4-announcement/</loc>
<lastmod>2017-12-22</lastmod>
<lastmod>2018-01-15</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//topics/3.5-announcement/</loc>
<lastmod>2017-12-22</lastmod>
<lastmod>2018-01-15</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//topics/3.6-announcement/</loc>
<lastmod>2017-12-22</lastmod>
<lastmod>2018-01-15</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//topics/3.7-announcement/</loc>
<lastmod>2017-12-22</lastmod>
<lastmod>2018-01-15</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//topics/kickstarter-announcement/</loc>
<lastmod>2017-12-22</lastmod>
<lastmod>2018-01-15</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//topics/mozilla-grant/</loc>
<lastmod>2017-12-22</lastmod>
<lastmod>2018-01-15</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//topics/funding/</loc>
<lastmod>2017-12-22</lastmod>
<lastmod>2018-01-15</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>http://www.django-rest-framework.org//topics/release-notes/</loc>
<lastmod>2017-12-22</lastmod>
<lastmod>2018-01-15</lastmod>
<changefreq>daily</changefreq>
</url>

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

@ -445,7 +445,7 @@
<p>The 3.0 release of Django REST framework is the result of almost four years of iteration and refinement. It comprehensively addresses some of the previous remaining design issues in serializers, fields and the generic views.</p>
<p><strong>This release is incremental in nature. There <em>are</em> some breaking API changes, and upgrading <em>will</em> require you to read the release notes carefully, but the migration path should otherwise be relatively straightforward.</strong></p>
<p>The difference in quality of the REST framework API and implementation should make writing, maintaining and debugging your application far easier.</p>
<p>3.0 is the first of three releases that have been funded by our recent <a href="http://kickstarter.com/projects/tomchristie/django-rest-framework-3">Kickstarter campaign</a>.</p>
<p>3.0 is the first of three releases that have been funded by our recent <a href="https://www.kickstarter.com/projects/tomchristie/django-rest-framework-3">Kickstarter campaign</a>.</p>
<p>As ever, a huge thank you to our many <a href="http://www.django-rest-framework.org/topics/kickstarter-announcement/#sponsors">wonderful sponsors</a>. If you're looking for a Django gig, and want to work with smart community-minded folks, you should probably check out that list and see who's hiring.</p>
<hr />
<h2 id="new-features"><a class="toclink" href="#new-features">New features</a></h2>
@ -464,7 +464,7 @@
<p>Significant new functionality continues to be planned for the 3.1 and 3.2 releases. These releases will correspond to the two <a href="https://www.kickstarter.com/projects/tomchristie/django-rest-framework-3">Kickstarter stretch goals</a> - "Feature improvements" and "Admin interface". Further 3.x releases will present simple upgrades, without the same level of fundamental API changes necessary for the 3.0 release.</p>
<hr />
<h4 id="rest-framework-under-the-hood"><a class="toclink" href="#rest-framework-under-the-hood">REST framework: Under the hood.</a></h4>
<p>This talk from the <a href="http://www.djangounderthehood.com/">Django: Under the Hood</a> event in Amsterdam, Nov 2014, gives some good background context on the design decisions behind 3.0.</p>
<p>This talk from the <a href="https://www.djangounderthehood.com/">Django: Under the Hood</a> event in Amsterdam, Nov 2014, gives some good background context on the design decisions behind 3.0.</p>
<iframe style="display: block; margin: 0 auto 0 auto" width="560" height="315" src="//www.youtube.com/embed/3cSsbe-tA0E" frameborder="0" allowfullscreen></iframe>
<hr />

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

@ -543,10 +543,10 @@ Host: example.org
<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>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>
<li>OAuth - <a href="https://jpadilla.github.io/django-rest-framework-oauth/">djangorestframework-oauth</a></li>
<li>XML - <a href="https://jpadilla.github.io/django-rest-framework-xml">djangorestframework-xml</a></li>
<li>YAML - <a href="https://jpadilla.github.io/django-rest-framework-yaml">djangorestframework-yaml</a></li>
<li>JSONP - <a href="https://jpadilla.github.io/django-rest-framework-jsonp">djangorestframework-jsonp</a></li>
</ul>
<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

6
topics/3.5-announcement/index.html
View File

@ -469,12 +469,12 @@ we strongly encourage you to invest in its continued development by
<li><a href="http://jobs.rover.com/" style="background-image: url(https://fund-rest-framework.s3.amazonaws.com/rover_130x130.png)">Rover.com</a></li>
<li><a href="https://getsentry.com/welcome/" style="background-image: url(https://fund-rest-framework.s3.amazonaws.com/sentry130.png)">Sentry</a></li>
<li><a href="https://getstream.io/?utm_source=drf&utm_medium=banner&utm_campaign=drf" style="background-image: url(https://fund-rest-framework.s3.amazonaws.com/stream-130.png)">Stream</a></li>
<li><a href="http://www.machinalis.com/#services" style="background-image: url(https://fund-rest-framework.s3.amazonaws.com/Machinalis130.png)">Machinalis</a></li>
<li><a href="https://www.machinalis.com/#services" style="background-image: url(https://fund-rest-framework.s3.amazonaws.com/Machinalis130.png)">Machinalis</a></li>
</ul>
<div style="clear: both; padding-bottom: 20px;"></div>
<p><em>Many thanks to all our <a href="https://fund.django-rest-framework.org/topics/funding/#our-sponsors">sponsors</a>, and in particular to our premium backers, <a href="http://jobs.rover.com/">Rover</a>, <a href="https://getsentry.com/welcome/">Sentry</a>, <a href="https://getstream.io/?utm_source=drf&amp;utm_medium=banner&amp;utm_campaign=drf">Stream</a>, and <a href="http://www.machinalis.com/#services">Machinalis</a>.</em></p>
<p><em>Many thanks to all our <a href="https://fund.django-rest-framework.org/topics/funding/#our-sponsors">sponsors</a>, and in particular to our premium backers, <a href="http://jobs.rover.com/">Rover</a>, <a href="https://getsentry.com/welcome/">Sentry</a>, <a href="https://getstream.io/?utm_source=drf&amp;utm_medium=banner&amp;utm_campaign=drf">Stream</a>, and <a href="https://www.machinalis.com/#services">Machinalis</a>.</em></p>
<hr />
<h2 id="improved-schema-generation"><a class="toclink" href="#improved-schema-generation">Improved schema generation</a></h2>
<p>Docstrings on views are now pulled through into schema definitions, allowing
@ -584,7 +584,7 @@ codes to identify differing kinds of failure...</p>
</code></pre>
<h2 id="client-upload-download-support"><a class="toclink" href="#client-upload-download-support">Client upload &amp; download support</a></h2>
<p>The Python <code>coreapi</code> client library and the Core API command line tool both
now fully support file <a href="http://core-api.github.io/python-client/api-guide/utils/#file">uploads</a> and <a href="http://core-api.github.io/python-client/api-guide/codecs/#downloadcodec">downloads</a>.</p>
now fully support file <a href="https://core-api.github.io/python-client/api-guide/utils/#file">uploads</a> and <a href="https://core-api.github.io/python-client/api-guide/codecs/#downloadcodec">downloads</a>.</p>
<hr />
<h2 id="deprecations"><a class="toclink" href="#deprecations">Deprecations</a></h2>
<h3 id="generating-schemas-from-router"><a class="toclink" href="#generating-schemas-from-router">Generating schemas from Router</a></h3>

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

@ -416,7 +416,7 @@
<h1 id="working-with-ajax-csrf-cors"><a class="toclink" href="#working-with-ajax-csrf-cors">Working with AJAX, CSRF &amp; CORS</a></h1>
<blockquote>
<p>"Take a close look at possible CSRF / XSRF vulnerabilities on your own websites. They're the worst kind of vulnerability &mdash; very easy to exploit by attackers, yet not so intuitively easy to understand for software developers, at least until you've been bitten by one."</p>
<p>&mdash; <a href="http://www.codinghorror.com/blog/2008/10/preventing-csrf-and-xsrf-attacks.html">Jeff Atwood</a></p>
<p>&mdash; <a href="https://blog.codinghorror.com/preventing-csrf-and-xsrf-attacks/">Jeff Atwood</a></p>
</blockquote>
<h2 id="javascript-clients"><a class="toclink" href="#javascript-clients">Javascript clients</a></h2>
<p>If you’re building a JavaScript client to interface with your Web API, you'll need to consider if the client can use the same authentication policy that is used by the rest of the website, and also determine if you need to use CSRF tokens or CORS headers.</p>
@ -432,7 +432,7 @@
<p>If you're using <code>SessionAuthentication</code> you'll need to include valid CSRF tokens for any <code>POST</code>, <code>PUT</code>, <code>PATCH</code> or <code>DELETE</code> operations.</p>
<p>In order to make AJAX requests, you need to include CSRF token in the HTTP header, as <a href="https://docs.djangoproject.com/en/stable/ref/csrf/#ajax">described in the Django documentation</a>.</p>
<h2 id="cors"><a class="toclink" href="#cors">CORS</a></h2>
<p><a href="http://www.w3.org/TR/cors/">Cross-Origin Resource Sharing</a> is a mechanism for allowing clients to interact with APIs that are hosted on a different domain. CORS works by requiring the server to include a specific set of headers that allow a browser to determine if and when cross-domain requests should be allowed.</p>
<p><a href="https://www.w3.org/TR/cors/">Cross-Origin Resource Sharing</a> is a mechanism for allowing clients to interact with APIs that are hosted on a different domain. CORS works by requiring the server to include a specific set of headers that allow a browser to determine if and when cross-domain requests should be allowed.</p>
<p>The best way to deal with CORS in REST framework is to add the required response headers in middleware. This ensures that CORS is supported transparently, without having to change any behavior in your views.</p>
<p><a href="https://github.com/ottoyiu/">Otto Yiu</a> maintains the <a href="https://github.com/ottoyiu/django-cors-headers/">django-cors-headers</a> package, which is known to work correctly with REST framework APIs.</p>

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

@ -416,7 +416,7 @@
<h1 id="the-browsable-api"><a class="toclink" href="#the-browsable-api">The Browsable API</a></h1>
<blockquote>
<p>It is a profoundly erroneous truism... that we should cultivate the habit of thinking of what we are doing. The precise opposite is the case. Civilization advances by extending the number of important operations which we can perform without thinking about them.</p>
<p>&mdash; <a href="http://en.wikiquote.org/wiki/Alfred_North_Whitehead">Alfred North Whitehead</a>, An Introduction to Mathematics (1911)</p>
<p>&mdash; <a href="https://en.wikiquote.org/wiki/Alfred_North_Whitehead">Alfred North Whitehead</a>, An Introduction to Mathematics (1911)</p>
</blockquote>
<p>API may stand for Application <em>Programming</em> Interface, but humans have to be able to read the APIs, too; someone has to do the programming. Django REST Framework supports generating human-friendly HTML output for each resource when the <code>HTML</code> format is requested. These pages allow for easy browsing of resources, as well as forms for submitting data to the resources using <code>POST</code>, <code>PUT</code>, and <code>DELETE</code>.</p>
<h2 id="urls"><a class="toclink" href="#urls">URLs</a></h2>
@ -424,7 +424,7 @@
<h2 id="formats"><a class="toclink" href="#formats">Formats</a></h2>
<p>By default, the API will return the format specified by the headers, which in the case of the browser is HTML. The format can be specified using <code>?format=</code> in the request, so you can look at the raw JSON response in a browser by adding <code>?format=json</code> to the URL. There are helpful extensions for viewing JSON in <a href="https://addons.mozilla.org/en-US/firefox/addon/jsonview/">Firefox</a> and <a href="https://chrome.google.com/webstore/detail/chklaanhfefbnpoihckbnefhakgolnmc">Chrome</a>.</p>
<h2 id="customizing"><a class="toclink" href="#customizing">Customizing</a></h2>
<p>The browsable API is built with <a href="http://getbootstrap.com">Twitter's Bootstrap</a> (v 3.3.5), making it easy to customize the look-and-feel.</p>
<p>The browsable API is built with <a href="https://getbootstrap.com/">Twitter's Bootstrap</a> (v 3.3.5), making it easy to customize the look-and-feel.</p>
<p>To customize the default style, create a template called <code>rest_framework/api.html</code> that extends from <code>rest_framework/base.html</code>. For example:</p>
<p><strong>templates/rest_framework/api.html</strong></p>
<pre><code>{% extends "rest_framework/base.html" %}
@ -437,13 +437,13 @@
&lt;link rel="stylesheet" href="/path/to/my/bootstrap.css" type="text/css"&gt;
{% endblock %}
</code></pre>
<p>Suitable pre-made replacement themes are available at <a href="http://bootswatch.com/">Bootswatch</a>. To use any of the Bootswatch themes, simply download the theme's <code>bootstrap.min.css</code> file, add it to your project, and replace the default one as described above.</p>
<p>Suitable pre-made replacement themes are available at <a href="https://bootswatch.com/">Bootswatch</a>. To use any of the Bootswatch themes, simply download the theme's <code>bootstrap.min.css</code> file, add it to your project, and replace the default one as described above.</p>
<p>You can also change the navbar variant, which by default is <code>navbar-inverse</code>, using the <code>bootstrap_navbar_variant</code> block. The empty <code>{% block bootstrap_navbar_variant %}{% endblock %}</code> will use the original Bootstrap navbar style.</p>
<p>Full example:</p>
<pre><code>{% extends "rest_framework/base.html" %}
{% block bootstrap_theme %}
&lt;link rel="stylesheet" href="http://bootswatch.com/flatly/bootstrap.min.css" type="text/css"&gt;
&lt;link rel="stylesheet" href="https://bootswatch.com/flatly/bootstrap.min.css" type="text/css"&gt;
{% endblock %}
{% block bootstrap_navbar_variant %}{% endblock %}
@ -463,7 +463,7 @@
<li><code>bodyclass</code> - Class attribute for the <code>&lt;body&gt;</code> tag, empty by default.</li>
<li><code>bootstrap_theme</code> - CSS for the Bootstrap theme.</li>
<li><code>bootstrap_navbar_variant</code> - CSS class for the navbar.</li>
<li><code>branding</code> - Branding section of the navbar, see <a href="http://getbootstrap.com/2.3.2/components.html#navbar">Bootstrap components</a>.</li>
<li><code>branding</code> - Branding section of the navbar, see <a href="https://getbootstrap.com/2.3.2/components.html#navbar">Bootstrap components</a>.</li>
<li><code>breadcrumbs</code> - Links showing resource nesting, allowing the user to go back up the resources. It's recommended to preserve these, but they can be overridden using the breadcrumbs block.</li>
<li><code>script</code> - JavaScript files for the page.</li>
<li><code>style</code> - CSS stylesheets for the page.</li>
@ -471,7 +471,7 @@
<li><code>userlinks</code> - This is a list of links on the right of the header, by default containing login/logout links. To add links instead of replace, use <code>{{ block.super }}</code> to preserve the authentication links.</li>
</ul>
<h4 id="components"><a class="toclink" href="#components">Components</a></h4>
<p>All of the standard <a href="http://getbootstrap.com/2.3.2/components.html">Bootstrap components</a> are available.</p>
<p>All of the standard <a href="https://getbootstrap.com/2.3.2/components.html">Bootstrap components</a> are available.</p>
<h4 id="tooltips"><a class="toclink" href="#tooltips">Tooltips</a></h4>
<p>The browsable API makes use of the Bootstrap tooltips component. Any element with the <code>js-tooltip</code> class and a <code>title</code> attribute has that title content will display a tooltip on hover events.</p>
<h3 id="login-template"><a class="toclink" href="#login-template">Login Template</a></h3>

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

@ -428,7 +428,7 @@
<h1 id="browser-enhancements"><a class="toclink" href="#browser-enhancements">Browser enhancements</a></h1>
<blockquote>
<p>"There are two noncontroversial uses for overloaded POST. The first is to <em>simulate</em> HTTP's uniform interface for clients like web browsers that don't support PUT or DELETE"</p>
<p>&mdash; <a href="http://www.amazon.com/Restful-Web-Services-Leonard-Richardson/dp/0596529260">RESTful Web Services</a>, Leonard Richardson &amp; Sam Ruby.</p>
<p>&mdash; <a href="https://www.amazon.com/RESTful-Web-Services-Leonard-Richardson/dp/0596529260">RESTful Web Services</a>, Leonard Richardson &amp; Sam Ruby.</p>
</blockquote>
<p>In order to allow the browsable API to function, there are a couple of browser enhancements that REST framework needs to provide.</p>
<p>As of version 3.3.0 onwards these are enabled with javascript, using the <a href="https://github.com/encode/ajax-form">ajax-form</a> library.</p>
@ -481,7 +481,7 @@ class MethodOverrideMiddleware(object):
</code></pre>
<h2 id="doesnt-html5-support-put-and-delete-forms"><a class="toclink" href="#doesnt-html5-support-put-and-delete-forms">Doesn't HTML5 support PUT and DELETE forms?</a></h2>
<p>Nope. It was at one point intended to support <code>PUT</code> and <code>DELETE</code> forms, but
was later <a href="http://www.w3.org/TR/html5-diff/#changes-2010-06-24">dropped from the spec</a>. There remains
was later <a href="https://www.w3.org/TR/html5-diff/#changes-2010-06-24">dropped from the spec</a>. There remains
<a href="http://amundsen.com/examples/put-delete-forms/">ongoing discussion</a> about adding support for <code>PUT</code> and <code>DELETE</code>,
as well as how to support content types other than form-encoded data.</p>

8
topics/contributing/index.html
View File

@ -458,13 +458,13 @@
<h1 id="contributing-to-rest-framework"><a class="toclink" href="#contributing-to-rest-framework">Contributing to REST framework</a></h1>
<blockquote>
<p>The world can only really be changed one piece at a time. The art is picking that piece.</p>
<p>&mdash; <a href="http://www.w3.org/People/Berners-Lee/FAQ.html">Tim Berners-Lee</a></p>
<p>&mdash; <a href="https://www.w3.org/People/Berners-Lee/FAQ.html">Tim Berners-Lee</a></p>
</blockquote>
<p>There are many ways you can contribute to Django REST framework. We'd like it to be a community-led project, so please get involved and help shape the future of the project.</p>
<h2 id="community"><a class="toclink" href="#community">Community</a></h2>
<p>The most important thing you can do to help push the REST framework project forward is to be actively involved wherever possible. Code contributions are often overvalued as being the primary way to get involved in a project, we don't believe that needs to be the case.</p>
<p>If you use REST framework, we'd love you to be vocal about your experiences with it - you might consider writing a blog post about using REST framework, or publishing a tutorial about building a project with a particular JavaScript framework. Experiences from beginners can be particularly helpful because you'll be in the best position to assess which bits of REST framework are more difficult to understand and work with.</p>
<p>Other really great ways you can help move the community forward include helping to answer questions on the <a href="https://groups.google.com/forum/?fromgroups#!forum/django-rest-framework">discussion group</a>, or setting up an <a href="http://stackexchange.com/filters/66475/rest-framework">email alert on StackOverflow</a> so that you get notified of any new questions with the <code>django-rest-framework</code> tag.</p>
<p>Other really great ways you can help move the community forward include helping to answer questions on the <a href="https://groups.google.com/forum/?fromgroups#!forum/django-rest-framework">discussion group</a>, or setting up an <a href="https://stackexchange.com/filters/66475/rest-framework">email alert on StackOverflow</a> so that you get notified of any new questions with the <code>django-rest-framework</code> tag.</p>
<p>When answering questions make sure to help future contributors find their way around by hyperlinking wherever possible to related threads and tickets, and include backlinks from those items if relevant.</p>
<h2 id="code-of-conduct"><a class="toclink" href="#code-of-conduct">Code of conduct</a></h2>
<p>Please keep the tone polite &amp; professional. For some users a discussion on the REST framework mailing list or ticket tracker may be their first engagement with the open source community. First impressions count, so let's try to make everyone feel welcome.</p>
@ -493,7 +493,7 @@
<p>To start developing on Django REST framework, clone the repo:</p>
<pre><code>git clone git@github.com:encode/django-rest-framework.git
</code></pre>
<p>Changes should broadly follow the <a href="http://www.python.org/dev/peps/pep-0008/">PEP 8</a> style conventions, and we recommend you set up your editor to automatically indicate non-conforming styles.</p>
<p>Changes should broadly follow the <a href="https://www.python.org/dev/peps/pep-0008/">PEP 8</a> style conventions, and we recommend you set up your editor to automatically indicate non-conforming styles.</p>
<h2 id="testing"><a class="toclink" href="#testing">Testing</a></h2>
<p>To run the tests, clone the repository, and then:</p>
<pre><code># Setup the virtual environment
@ -544,7 +544,7 @@ pip install -r requirements.txt
<h2 id="managing-compatibility-issues"><a class="toclink" href="#managing-compatibility-issues">Managing compatibility issues</a></h2>
<p>Sometimes, in order to ensure your code works on various different versions of Django, Python or third party libraries, you'll need to run slightly different code depending on the environment. Any code that branches in this way should be isolated into the <code>compat.py</code> module, and should provide a single common interface that the rest of the codebase can use.</p>
<h1 id="documentation"><a class="toclink" href="#documentation">Documentation</a></h1>
<p>The documentation for REST framework is built from the <a href="http://daringfireball.net/projects/markdown/basics">Markdown</a> source files in <a href="https://github.com/encode/django-rest-framework/tree/master/docs">the docs directory</a>.</p>
<p>The documentation for REST framework is built from the <a href="https://daringfireball.net/projects/markdown/basics">Markdown</a> source files in <a href="https://github.com/encode/django-rest-framework/tree/master/docs">the docs directory</a>.</p>
<p>There are many great Markdown editors that make working with the documentation really easy. The <a href="http://mouapp.com/">Mou editor for Mac</a> is one such editor that comes highly recommended.</p>
<h2 id="building-the-documentation"><a class="toclink" href="#building-the-documentation">Building the documentation</a></h2>
<p>To build the documentation, install MkDocs with <code>pip install mkdocs</code> and then run the following command.</p>

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

@ -531,6 +531,14 @@ For example:</p>
<hr />
<h2 id="third-party-packages"><a class="toclink" href="#third-party-packages">Third party packages</a></h2>
<p>There are a number of mature third-party packages for providing API documentation.</p>
<h4 id="drf-yasg-yet-another-swagger-generator"><a class="toclink" href="#drf-yasg-yet-another-swagger-generator">drf-yasg - Yet Another Swagger Generator</a></h4>
<p><a href="https://github.com/axnsan12/drf-yasg/">drf-yasg</a> is a <a href="https://swagger.io/">Swagger</a> generation tool implemented without using the schema generation provided
by Django Rest Framework.</p>
<p>It aims to implement as much of the <a href="https://openapis.org/">OpenAPI</a> specification as possible - nested schemas, named models,
response bodies, enum/pattern/min/max validators, form parameters, etc. - and to generate documents usable with code
generation tools like <code>swagger-codegen</code>.</p>
<p>This also translates into a very useful interactive documentation viewer in the form of <code>swagger-ui</code>:</p>
<p><img alt="Screenshot - drf-yasg" src="../../img/drf-yasg.png" /></p>
<h4 id="drf-openapi"><a class="toclink" href="#drf-openapi">DRF OpenAPI</a></h4>
<p><a href="https://github.com/limdauto/drf_openapi/">DRF OpenAPI</a> bridges the gap between OpenAPI specification and tool chain with the schema exposed
out-of-the-box by Django Rest Framework. Its goals are:</p>
@ -545,13 +553,13 @@ out-of-the-box by Django Rest Framework. Its goals are:</p>
<p><img alt="Screenshot - DRF OpenAPI" src="../../img/drf-openapi.png" /></p>
<hr />
<h4 id="drf-docs"><a class="toclink" href="#drf-docs">DRF Docs</a></h4>
<p><a href="https://github.com/ekonstantinidis/django-rest-framework-docs">DRF Docs</a> allows you to document Web APIs made with Django REST Framework and it is authored by Emmanouil Konstantinidis. It's made to work out of the box and its setup should not take more than a couple of minutes. Complete documentation can be found on the <a href="http://www.drfdocs.com/">website</a> while there is also a <a href="http://demo.drfdocs.com/">demo</a> available for people to see what it looks like. <strong>Live API Endpoints</strong> allow you to utilize the endpoints from within the documentation in a neat way.</p>
<p><a href="https://github.com/ekonstantinidis/django-rest-framework-docs">DRF Docs</a> allows you to document Web APIs made with Django REST Framework and it is authored by Emmanouil Konstantinidis. It's made to work out of the box and its setup should not take more than a couple of minutes. Complete documentation can be found on the <a href="https://www.drfdocs.com/">website</a> while there is also a <a href="http://demo.drfdocs.com/">demo</a> available for people to see what it looks like. <strong>Live API Endpoints</strong> allow you to utilize the endpoints from within the documentation in a neat way.</p>
<p>Features include customizing the template with your branding, settings for hiding the docs depending on the environment and more.</p>
<p>Both this package and Django REST Swagger are fully documented, well supported, and come highly recommended.</p>
<p><img alt="Screenshot - DRF docs" src="../../img/drfdocs.png" /></p>
<hr />
<h4 id="django-rest-swagger"><a class="toclink" href="#django-rest-swagger">Django REST Swagger</a></h4>
<p>Marc Gibbons' <a href="https://github.com/marcgibbons/django-rest-swagger">Django REST Swagger</a> integrates REST framework with the <a href="https://developers.helloreverb.com/swagger/">Swagger</a> API documentation tool. The package produces well presented API documentation, and includes interactive tools for testing API endpoints.</p>
<p>Marc Gibbons' <a href="https://github.com/marcgibbons/django-rest-swagger">Django REST Swagger</a> integrates REST framework with the <a href="https://swagger.io/">Swagger</a> API documentation tool. The package produces well presented API documentation, and includes interactive tools for testing API endpoints.</p>
<p>Django REST Swagger supports REST framework versions 2.3 and above.</p>
<p>Mark is also the author of the <a href="https://github.com/marcgibbons/django-rest-framework-docs">REST Framework Docs</a> package which offers clean, simple autogenerated documentation for your API but is deprecated and has moved to Django REST Swagger.</p>
<p>Both this package and DRF docs are fully documented, well supported, and come highly recommended.</p>
@ -581,7 +589,7 @@ out-of-the-box by Django Rest Framework. Its goals are:</p>
<p><img alt="whole structure" src="http://joxi.ru/52aBGNI4k3oyA0.jpg" /></p>
<hr />
<h4 id="apiary"><a class="toclink" href="#apiary">Apiary</a></h4>
<p>There are various other online tools and services for providing API documentation. One notable service is <a href="http://apiary.io/">Apiary</a>. With Apiary, you describe your API using a simple markdown-like syntax. The generated documentation includes API interaction, a mock server for testing &amp; prototyping, and various other tools.</p>
<p>There are various other online tools and services for providing API documentation. One notable service is <a href="https://apiary.io/">Apiary</a>. With Apiary, you describe your API using a simple markdown-like syntax. The generated documentation includes API interaction, a mock server for testing &amp; prototyping, and various other tools.</p>
<p><img alt="Screenshot - Apiary" src="../../img/apiary.png" /></p>
<hr />
<h2 id="self-describing-apis"><a class="toclink" href="#self-describing-apis">Self describing APIs</a></h2>
@ -594,7 +602,7 @@ out-of-the-box by Django Rest Framework. Its goals are:</p>
<p>When working with viewsets, an appropriate suffix is appended to each generated view. For example, the view set <code>UserViewSet</code> will generate views named <code>User List</code> and <code>User Instance</code>.</p>
<h4 id="setting-the-description"><a class="toclink" href="#setting-the-description">Setting the description</a></h4>
<p>The description in the browsable API is generated from the docstring of the view or viewset.</p>
<p>If the python <code>markdown</code> library is installed, then <a href="http://daringfireball.net/projects/markdown/">markdown syntax</a> may be used in the docstring, and will be converted to HTML in the browsable API. For example:</p>
<p>If the python <code>markdown</code> library is installed, then <a href="https://daringfireball.net/projects/markdown/">markdown syntax</a> may be used in the docstring, and will be converted to HTML in the browsable API. For example:</p>
<pre><code>class AccountListView(views.APIView):
"""
Returns a list of all **active** accounts in the system.

2
topics/internationalization/index.html
View File

@ -416,7 +416,7 @@
<h1 id="internationalization"><a class="toclink" href="#internationalization">Internationalization</a></h1>
<blockquote>
<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>
<p>&mdash; <a href="https://youtu.be/Wa0VfS2q94Y">Jannis Leidel, speaking at Django Under the Hood, 2015</a>.</p>
</blockquote>
<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>

2
topics/jobs/index.html
View File

@ -415,7 +415,7 @@
<li><a href="https://djangojobs.net/jobs/">https://djangojobs.net/jobs/</a></li>
<li><a href="http://djangojobbers.com">http://djangojobbers.com</a></li>
<li><a href="https://www.indeed.com/q-Django-jobs.html">https://www.indeed.com/q-Django-jobs.html</a></li>
<li><a href="http://stackoverflow.com/jobs/developer-jobs-using-django">http://stackoverflow.com/jobs/developer-jobs-using-django</a></li>
<li><a href="https://stackoverflow.com/jobs/developer-jobs-using-django">https://stackoverflow.com/jobs/developer-jobs-using-django</a></li>
<li><a href="https://www.upwork.com/o/jobs/browse/skill/django-framework/">https://www.upwork.com/o/jobs/browse/skill/django-framework/</a></li>
<li><a href="https://www.technojobs.co.uk/django-jobs">https://www.technojobs.co.uk/django-jobs</a></li>
<li><a href="https://remoteok.io/remote-django-jobs">https://remoteok.io/remote-django-jobs</a></li>

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

@ -464,12 +464,12 @@
<li><a href="https://www.schubergphilis.com/" rel="nofollow" style="background-image:url(../../img/sponsors/2-schuberg_philis.png);">Schuberg Philis</a></li>
<li><a href="http://prorenata.se/" rel="nofollow" style="background-image:url(../../img/sponsors/2-prorenata.png);">ProReNata AB</a></li>
<li><a href="https://www.sgawebsites.com/" rel="nofollow" style="background-image:url(../../img/sponsors/2-sga.png);">SGA Websites</a></li>
<li><a href="http://www.sirono.com/" rel="nofollow" style="background-image:url(../../img/sponsors/2-sirono.png);">Sirono</a></li>
<li><a href="http://www.vinta.com.br/" rel="nofollow" style="background-image:url(../../img/sponsors/2-vinta.png);">Vinta Software Studio</a></li>
<li><a href="http://www.rapasso.nl/index.php/en" rel="nofollow" style="background-image:url(../../img/sponsors/2-rapasso.png);">Rapasso</a></li>
<li><a href="https://www.sirono.com/" rel="nofollow" style="background-image:url(../../img/sponsors/2-sirono.png);">Sirono</a></li>
<li><a href="https://www.vinta.com.br/" rel="nofollow" style="background-image:url(../../img/sponsors/2-vinta.png);">Vinta Software Studio</a></li>
<li><a href="https://www.rapasso.nl/" rel="nofollow" style="background-image:url(../../img/sponsors/2-rapasso.png);">Rapasso</a></li>
<li><a href="https://mirusresearch.com/" rel="nofollow" style="background-image:url(../../img/sponsors/2-mirus_research.png);">Mirus Research</a></li>
<li><a href="http://hipolabs.com" rel="nofollow" style="background-image:url(../../img/sponsors/2-hipo.png);">Hipo</a></li>
<li><a href="http://www.byte.nl" rel="nofollow" style="background-image:url(../../img/sponsors/2-byte.png);">Byte</a></li>
<li><a href="https://hipolabs.com/" rel="nofollow" style="background-image:url(../../img/sponsors/2-hipo.png);">Hipo</a></li>
<li><a href="https://www.byte.nl/" rel="nofollow" style="background-image:url(../../img/sponsors/2-byte.png);">Byte</a></li>
<li><a href="http://lightningkite.com/" rel="nofollow" style="background-image:url(../../img/sponsors/2-lightning_kite.png);">Lightning Kite</a></li>
<li><a href="https://opbeat.com/" rel="nofollow" style="background-image:url(../../img/sponsors/2-opbeat.png);">Opbeat</a></li>
<li><a href="https://koordinates.com" rel="nofollow" style="background-image:url(../../img/sponsors/2-koordinates.png);">Koordinates</a></li>
@ -477,7 +477,7 @@
<li><a href="http://singinghorsestudio.com" rel="nofollow" style="background-image:url(../../img/sponsors/2-singing-horse.png);">Singing Horse Studio Ltd.</a></li>
<li><a href="https://www.heroku.com/" rel="nofollow" style="background-image:url(../../img/sponsors/2-heroku.png);">Heroku</a></li>
<li><a href="https://www.rheinwerk-verlag.de/" rel="nofollow" style="background-image:url(../../img/sponsors/2-rheinwerk_verlag.png);">Rheinwerk Verlag</a></li>
<li><a href="http://www.securitycompass.com/" rel="nofollow" style="background-image:url(../../img/sponsors/2-security_compass.png);">Security Compass</a></li>
<li><a href="https://www.securitycompass.com/" rel="nofollow" style="background-image:url(../../img/sponsors/2-security_compass.png);">Security Compass</a></li>
<li><a href="https://www.djangoproject.com/foundation/" rel="nofollow" style="background-image:url(../../img/sponsors/2-django.png);">Django Software Foundation</a></li>
<li><a href="http://www.hipflaskapp.com" rel="nofollow" style="background-image:url(../../img/sponsors/2-hipflask.png);">Hipflask</a></li>
<li><a href="http://www.crate.io/" rel="nofollow" style="background-image:url(../../img/sponsors/2-crate.png);">Crate</a></li>
@ -494,38 +494,38 @@
<h3 id="silver-sponsors"><a class="toclink" href="#silver-sponsors">Silver sponsors</a></h3>
<p>The serious financial contribution that our silver sponsors have made is very much appreciated. I'd like to say a particular thank&nbsp;you to individuals who have chosen to privately support the project at this level.</p>
<ul class="sponsor silver">
<li><a href="http://www.imtapps.com/" rel="nofollow" style="background-image:url(../../img/sponsors/3-imt_computer_services.png);">IMT Computer Services</a></li>
<li><a href="http://wildfish.com/" rel="nofollow" style="background-image:url(../../img/sponsors/3-wildfish.png);">Wildfish</a></li>
<li><a href="http://www.thermondo.de/" rel="nofollow" style="background-image:url(../../img/sponsors/3-thermondo-gmbh.png);">Thermondo GmbH</a></li>
<li><a href="http://providenz.fr/" rel="nofollow" style="background-image:url(../../img/sponsors/3-providenz.png);">Providenz</a></li>
<li><a href="https://www.imtapps.com/" rel="nofollow" style="background-image:url(../../img/sponsors/3-imt_computer_services.png);">IMT Computer Services</a></li>
<li><a href="https://wildfish.com/" rel="nofollow" style="background-image:url(../../img/sponsors/3-wildfish.png);">Wildfish</a></li>
<li><a href="https://www.thermondo.de/" rel="nofollow" style="background-image:url(../../img/sponsors/3-thermondo-gmbh.png);">Thermondo GmbH</a></li>
<li><a href="https://providenz.fr/" rel="nofollow" style="background-image:url(../../img/sponsors/3-providenz.png);">Providenz</a></li>
<li><a href="https://www.alwaysdata.com" rel="nofollow" style="background-image:url(../../img/sponsors/3-alwaysdata.png);">alwaysdata.com</a></li>
<li><a href="http://www.triggeredmessaging.com/" rel="nofollow" style="background-image:url(../../img/sponsors/3-triggered_messaging.png);">Triggered Messaging</a></li>
<li><a href="https://www.freshrelevance.com/" rel="nofollow" style="background-image:url(../../img/sponsors/3-triggered_messaging.png);">Triggered Messaging</a></li>
<li><a href="https://www.ipushpull.com/" rel="nofollow" style="background-image:url(../../img/sponsors/3-ipushpull.png);">PushPull Technology Ltd</a></li>
<li><a href="http://www.transcode.de/" rel="nofollow" style="background-image:url(../../img/sponsors/3-transcode.png);">Transcode</a></li>
<li><a href="https://garfo.io/" rel="nofollow" style="background-image:url(../../img/sponsors/3-garfo.png);">Garfo</a></li>
<li><a href="https://goshippo.com/" rel="nofollow" style="background-image:url(../../img/sponsors/3-shippo.png);">Shippo</a></li>
<li><a href="http://www.gizmag.com/" rel="nofollow" style="background-image:url(../../img/sponsors/3-gizmag.png);">Gizmag</a></li>
<li><a href="http://www.tivix.com/" rel="nofollow" style="background-image:url(../../img/sponsors/3-tivix.png);">Tivix</a></li>
<li><a href="http://www.safaribooksonline.com/" rel="nofollow" style="background-image:url(../../img/sponsors/3-safari.png);">Safari</a></li>
<li><a href="https://www.safaribooksonline.com/" rel="nofollow" style="background-image:url(../../img/sponsors/3-safari.png);">Safari</a></li>
<li><a href="http://brightloop.com/" rel="nofollow" style="background-image:url(../../img/sponsors/3-brightloop.png);">Bright Loop</a></li>
<li><a href="http://www.aba-systems.com.au/" rel="nofollow" style="background-image:url(../../img/sponsors/3-aba.png);">ABA Systems</a></li>
<li><a href="http://beefarm.ru/" rel="nofollow" style="background-image:url(../../img/sponsors/3-beefarm.png);">beefarm.ru</a></li>
<li><a href="http://www.vzzual.com/" rel="nofollow" style="background-image:url(../../img/sponsors/3-vzzual.png);">Vzzual.com</a></li>
<li><a href="http://infinite-code.com/" rel="nofollow" style="background-image:url(../../img/sponsors/3-infinite_code.png);">Infinite Code</a></li>
<li><a href="http://crosswordtracker.com/" rel="nofollow" style="background-image:url(../../img/sponsors/3-crosswordtracker.png);">Crossword Tracker</a></li>
<li><a href="https://crosswordtracker.com/" rel="nofollow" style="background-image:url(../../img/sponsors/3-crosswordtracker.png);">Crossword Tracker</a></li>
<li><a href="https://www.pkgfarm.com/" rel="nofollow" style="background-image:url(../../img/sponsors/3-pkgfarm.png);">PkgFarm</a></li>
<li><a href="http://life.tl/" rel="nofollow" style="background-image:url(../../img/sponsors/3-life_the_game.png);">Life. The Game.</a></li>
<li><a href="http://blimp.io/" rel="nofollow" style="background-image:url(../../img/sponsors/3-blimp.png);">Blimp</a></li>
<li><a href="http://pathwright.com" rel="nofollow" style="background-image:url(../../img/sponsors/3-pathwright.png);">Pathwright</a></li>
<li><a href="http://fluxility.com/" rel="nofollow" style="background-image:url(../../img/sponsors/3-fluxility.png);">Fluxility</a></li>
<li><a href="http://teonite.com/" rel="nofollow" style="background-image:url(../../img/sponsors/3-teonite.png);">Teonite</a></li>
<li><a href="http://trackmaven.com/" rel="nofollow" style="background-image:url(../../img/sponsors/3-trackmaven.png);">TrackMaven</a></li>
<li><a href="https://www.pathwright.com/" rel="nofollow" style="background-image:url(../../img/sponsors/3-pathwright.png);">Pathwright</a></li>
<li><a href="https://fluxility.com/" rel="nofollow" style="background-image:url(../../img/sponsors/3-fluxility.png);">Fluxility</a></li>
<li><a href="https://teonite.com/" rel="nofollow" style="background-image:url(../../img/sponsors/3-teonite.png);">Teonite</a></li>
<li><a href="https://trackmaven.com/" rel="nofollow" style="background-image:url(../../img/sponsors/3-trackmaven.png);">TrackMaven</a></li>
<li><a href="http://www.phurba.net/" rel="nofollow" style="background-image:url(../../img/sponsors/3-phurba.png);">Phurba</a></li>
<li><a href="http://www.nephila.co.uk/" rel="nofollow" style="background-image:url(../../img/sponsors/3-nephila.png);">Nephila</a></li>
<li><a href="https://www.nephila.it/it/" rel="nofollow" style="background-image:url(../../img/sponsors/3-nephila.png);">Nephila</a></li>
<li><a href="http://www.aditium.com/" rel="nofollow" style="background-image:url(../../img/sponsors/3-aditium.png);">Aditium</a></li>
<li><a href="http://www.eyesopen.com/" rel="nofollow" style="background-image:url(../../img/sponsors/3-openeye.png);">OpenEye Scientific Software</a></li>
<li><a href="https://www.eyesopen.com/" rel="nofollow" style="background-image:url(../../img/sponsors/3-openeye.png);">OpenEye Scientific Software</a></li>
<li><a href="https://holvi.com/" rel="nofollow" style="background-image:url(../../img/sponsors/3-holvi.png);">Holvi</a></li>
<li><a href="http://cantemo.com/" rel="nofollow" style="background-image:url(../../img/sponsors/3-cantemo.gif);">Cantemo</a></li>
<li><a href="https://www.cantemo.com/" rel="nofollow" style="background-image:url(../../img/sponsors/3-cantemo.gif);">Cantemo</a></li>
<li><a href="https://www.makespace.com/" rel="nofollow" style="background-image:url(../../img/sponsors/3-makespace.png);">MakeSpace</a></li>
<li><a href="https://www.ax-semantics.com/" rel="nofollow" style="background-image:url(../../img/sponsors/3-ax_semantics.png);">AX Semantics</a></li>
<li><a href="http://istrategylabs.com/" rel="nofollow" style="background-image:url(../../img/sponsors/3-isl.png);">ISL</a></li>
@ -533,7 +533,7 @@
<div style="clear: both; padding-bottom: 40px;"></div>
<p><strong>Individual backers</strong>: Paul Hallett, <a href="http://www.paulwhippconsulting.com/">Paul Whipp</a>, Dylan Roy, Jannis Leidel, <a href="https://linovia.com/en/">Xavier Ordoquy</a>, <a href="http://spielmannsolutions.com/">Johannes Spielmann</a>, <a href="http://brooklynhacker.com/">Rob Spectre</a>, <a href="http://chrisheisel.com/">Chris Heisel</a>, Marwan Alsabbagh, Haris Ali, Tuomas Toivonen.</p>
<p><strong>Individual backers</strong>: Paul Hallett, <a href="http://www.paulwhippconsulting.com/">Paul Whipp</a>, Dylan Roy, Jannis Leidel, <a href="https://linovia.com/en/">Xavier Ordoquy</a>, <a href="http://spielmannsolutions.com/">Johannes Spielmann</a>, <a href="http://brooklynhacker.com/">Rob Spectre</a>, <a href="https://chrisheisel.com/">Chris Heisel</a>, Marwan Alsabbagh, Haris Ali, Tuomas Toivonen.</p>
<hr />
<h3 id="advocates"><a class="toclink" href="#advocates">Advocates</a></h3>
<p>The following individuals made a significant financial contribution to the development of Django REST framework 3, for which I can only offer a huge, warm and sincere thank you!</p>

2
topics/mozilla-grant/index.html
View File

@ -438,7 +438,7 @@
</ul>
<h2 id="accountability"><a class="toclink" href="#accountability">Accountability</a></h2>
<p>In order to ensure that I can be fully focused on trying to secure a sustainable
&amp; well-funded open source business I will be leaving my current role at <a href="http://www.dabapps.com">DabApps</a>
&amp; well-funded open source business I will be leaving my current role at <a href="https://www.dabapps.com/">DabApps</a>
at the end of May 2016.</p>
<p>I have formed a UK limited company, <a href="http://www.encode.io">Encode</a>, which will
act as the business entity behind REST framework. I will be issuing monthly reports

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

@ -428,7 +428,7 @@
</blockquote>
<p>This document outlines our project management processes for REST framework.</p>
<p>The aim is to ensure that the project has a high
<a href="http://en.wikipedia.org/wiki/Bus_factor">"bus factor"</a>, and can continue to remain well supported for the foreseeable future. Suggestions for improvements to our process are welcome.</p>
<a href="https://en.wikipedia.org/wiki/Bus_factor">"bus factor"</a>, and can continue to remain well supported for the foreseeable future. Suggestions for improvements to our process are welcome.</p>
<hr />
<h2 id="maintenance-team"><a class="toclink" href="#maintenance-team">Maintenance team</a></h2>
<p>We have a quarterly maintenance cycle where new members may join the maintenance team. We currently cap the size of the team at 5 members, and may encourage folks to step out of the team for a cycle to allow new members to participate.</p>
@ -512,6 +512,11 @@ During development cycle:
Checklist:
- [ ] Create pull request for [release notes](https://github.com/encode/django-rest-framework/blob/master/docs/topics/release-notes.md) based on the [*.*.* milestone](https://github.com/encode/django-rest-framework/milestones/***).
- [ ] Update supported versions:
- [ ] `setup.py` `python_requires` list
- [ ] `setup.py` Python &amp; Django version trove classifiers
- [ ] `README` Python &amp; Django versions
- [ ] `docs` Python &amp; Django versions
- [ ] Update the translations from [transifex](http://www.django-rest-framework.org/topics/project-management/#translations).
- [ ] Ensure the pull request increments the version to `*.*.*` in [`restframework/__init__.py`](https://github.com/encode/django-rest-framework/blob/master/rest_framework/__init__.py).
- [ ] Confirm with @tomchristie that release is finalized and ready to go.
@ -578,7 +583,7 @@ django-admin.py compilemessages
<ul>
<li><a href="https://github.com/encode/django-rest-framework/issues/2162">Consider moving the repo into a proper GitHub organization</a>.</li>
<li>Ensure <code>@jamie</code> has back-up access to the <code>django-rest-framework.org</code> domain setup and admin.</li>
<li>Document ownership of the <a href="http://restframework.herokuapp.com/">live example</a> API.</li>
<li>Document ownership of the <a href="https://restframework.herokuapp.com/">live example</a> API.</li>
<li>Document ownership of the <a href="https://groups.google.com/forum/#!forum/django-rest-framework">mailing list</a> and IRC channel.</li>
<li>Document ownership and management of the security mailing list.</li>
</ul>

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

@ -416,19 +416,19 @@
<h1 id="rest-hypermedia-hateoas"><a class="toclink" href="#rest-hypermedia-hateoas">REST, Hypermedia &amp; HATEOAS</a></h1>
<blockquote>
<p>You keep using that word "REST". I do not think it means what you think it means.</p>
<p>&mdash; Mike Amundsen, <a href="http://vimeo.com/channels/restfest/page:2">REST fest 2012 keynote</a>.</p>
<p>&mdash; Mike Amundsen, <a href="https://vimeo.com/channels/restfest/page:2">REST fest 2012 keynote</a>.</p>
</blockquote>
<p>First off, the disclaimer. The name "Django REST framework" was decided back in early 2011 and was chosen simply to sure the project would be easily found by developers. Throughout the documentation we try to use the more simple and technically correct terminology of "Web APIs".</p>
<p>If you are serious about designing a Hypermedia API, you should look to resources outside of this documentation to help inform your design choices.</p>
<p>The following fall into the "required reading" category.</p>
<ul>
<li>Roy Fielding's dissertation - <a href="http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm">Architectural Styles and
<li>Roy Fielding's dissertation - <a href="https://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm">Architectural Styles and
the Design of Network-based Software Architectures</a>.</li>
<li>Roy Fielding's "<a href="http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven">REST APIs must be hypertext-driven</a>" blog post.</li>
<li>Leonard Richardson &amp; Mike Amundsen's <a href="http://restfulwebapis.org/">RESTful Web APIs</a>.</li>
<li>Mike Amundsen's <a href="http://www.amazon.com/Building-Hypermedia-APIs-HTML5-Node/dp/1449306578">Building Hypermedia APIs with HTML5 and Node</a>.</li>
<li>Mike Amundsen's <a href="https://www.amazon.com/Building-Hypermedia-APIs-HTML5-Node/dp/1449306578">Building Hypermedia APIs with HTML5 and Node</a>.</li>
<li>Steve Klabnik's <a href="http://designinghypermediaapis.com/">Designing Hypermedia APIs</a>.</li>
<li>The <a href="http://martinfowler.com/articles/richardsonMaturityModel.html">Richardson Maturity Model</a>.</li>
<li>The <a href="https://martinfowler.com/articles/richardsonMaturityModel.html">Richardson Maturity Model</a>.</li>
</ul>
<p>For a more thorough background, check out Klabnik's <a href="http://blog.steveklabnik.com/posts/2012-02-27-hypermedia-api-reading-list">Hypermedia API reading list</a>.</p>
<h2 id="building-hypermedia-apis-with-rest-framework"><a class="toclink" href="#building-hypermedia-apis-with-rest-framework">Building Hypermedia APIs with REST framework</a></h2>

4
topics/third-party-packages/index.html
View File

@ -469,7 +469,7 @@ You probably want to also tag the version now:
git push --tags
</code></pre>
<p>After releasing a new version to PyPI, it's always a good idea to tag the version and make available as a GitHub Release.</p>
<p>We recommend to follow <a href="http://semver.org/">Semantic Versioning</a> for your package's versions.</p>
<p>We recommend to follow <a href="https://semver.org/">Semantic Versioning</a> for your package's versions.</p>
<h3 id="development"><a class="toclink" href="#development">Development</a></h3>
<h4 id="version-requirements"><a class="toclink" href="#version-requirements">Version requirements</a></h4>
<p>The cookiecutter template assumes a set of supported versions will be provided for Python and Django. Make sure you correctly update your requirements, docs, <code>tox.ini</code>, <code>.travis.yml</code>, and <code>setup.py</code> to match the set of versions you wish to support.</p>
@ -576,7 +576,7 @@ You probably want to also tag the version now:
<h3 id="routers"><a class="toclink" href="#routers">Routers</a></h3>
<ul>
<li><a href="https://github.com/alanjds/drf-nested-routers">drf-nested-routers</a> - Provides routers and relationship fields for working with nested resources.</li>
<li><a href="http://wq.io/docs/about-rest">wq.db.rest</a> - Provides an admin-style model registration API with reasonable default URLs and viewsets.</li>
<li><a href="https://wq.io/docs/about-rest">wq.db.rest</a> - Provides an admin-style model registration API with reasonable default URLs and viewsets.</li>
</ul>
<h3 id="parsers"><a class="toclink" href="#parsers">Parsers</a></h3>
<ul>

24
topics/tutorials-and-resources/index.html
View File

@ -431,18 +431,18 @@
<h2 id="tutorials"><a class="toclink" href="#tutorials">Tutorials</a></h2>
<ul>
<li><a href="http://code.tutsplus.com/tutorials/beginners-guide-to-the-django-rest-framework--cms-19786">Beginner's Guide to the Django REST Framework</a></li>
<li><a href="https://code.tutsplus.com/tutorials/beginners-guide-to-the-django-rest-framework--cms-19786">Beginner's Guide to the Django REST Framework</a></li>
<li><a href="https://realpython.com/blog/python/django-rest-framework-quick-start/">Django REST Framework - An Introduction</a></li>
<li><a href="https://tests4geeks.com/django-rest-framework-tutorial/">Django REST Framework Tutorial</a></li>
<li><a href="https://teamtreehouse.com/library/django-rest-framework">Django REST Framework Course</a></li>
<li><a href="http://agiliq.com/blog/2014/12/building-a-restful-api-with-django-rest-framework/">Building a RESTful API with Django REST Framework</a></li>
<li><a href="https://agiliq.com/blog/2014/12/building-a-restful-api-with-django-rest-framework/">Building a RESTful API with Django REST Framework</a></li>
<li><a href="http://blog.kevinastone.com/getting-started-with-django-rest-framework-and-angularjs.html">Getting Started with Django REST Framework and AngularJS</a></li>
<li><a href="http://mourafiq.com/2013/07/01/end-to-end-web-app-with-django-angular-1.html">End to End Web App with Django REST Framework &amp; AngularJS</a></li>
<li><a href="https://godjango.com/41-start-your-api-django-rest-framework-part-1/">Start Your API - Django REST Framework Part 1</a></li>
<li><a href="https://godjango.com/43-permissions-authentication-django-rest-framework-part-2/">Permissions &amp; Authentication - Django REST Framework Part 2</a></li>
<li><a href="https://godjango.com/45-viewsets-and-routers-django-rest-framework-part-3/">ViewSets and Routers - Django REST Framework Part 3</a></li>
<li><a href="http://richardtier.com/2014/02/25/django-rest-framework-user-endpoint/">Django REST Framework User Endpoint</a></li>
<li><a href="http://richardtier.com/2014/03/06/110/">Check Credentials Using Django REST Framework</a></li>
<li><a href="https://richardtier.com/2014/02/25/django-rest-framework-user-endpoint/">Django REST Framework User Endpoint</a></li>
<li><a href="https://richardtier.com/2014/03/06/110/">Check Credentials Using Django REST Framework</a></li>
<li><a href="https://www.andreagrandi.it/2016/09/28/creating-production-ready-api-python-django-rest-framework-part-1/">Creating a Production Ready API with Python and Django REST Framework – Part 1</a></li>
<li><a href="https://www.andreagrandi.it/2016/10/01/creating-a-production-ready-api-with-python-and-django-rest-framework-part-2/">Creating a Production Ready API with Python and Django REST Framework – Part 2</a></li>
</ul>
@ -467,14 +467,14 @@
</ul>
<h2 id="articles"><a class="toclink" href="#articles">Articles</a></h2>
<ul>
<li><a href="http://dabapps.com/blog/api-performance-profiling-django-rest-framework/">Web API performance: Profiling Django REST Framework</a></li>
<li><a href="https://www.dabapps.com/blog/api-performance-profiling-django-rest-framework/">Web API performance: Profiling Django REST Framework</a></li>
<li><a href="https://bnotions.com/api-development-with-django-and-django-rest-framework/">API Development with Django and Django REST Framework</a></li>
<li><a href="http://machinalis.com/blog/pandas-django-rest-framework-bokeh/">Integrating Pandas, Django REST Framework and Bokeh</a></li>
<li><a href="http://machinalis.com/blog/controlling-uncertainty-on-web-applications-and-apis/">Controlling Uncertainty on Web Applications and APIs</a></li>
<li><a href="http://machinalis.com/blog/full-text-search-on-django-rest-framework/">Full Text Search in Django REST Framework with Database Backends</a></li>
<li><a href="http://machinalis.com/blog/oauth2-authentication/">OAuth2 Authentication with Django REST Framework and Custom Third-Party OAuth2 Backends</a></li>
<li><a href="http://machinalis.com/blog/nested-resources-with-django/">Nested Resources with Django REST Framework</a></li>
<li><a href="http://machinalis.com/blog/image-fields-with-django-rest-framework/">Image Fields with Django REST Framework</a></li>
<li><a href="https://machinalis.com/blog/pandas-django-rest-framework-bokeh/">Integrating Pandas, Django REST Framework and Bokeh</a></li>
<li><a href="https://machinalis.com/blog/controlling-uncertainty-on-web-applications-and-apis/">Controlling Uncertainty on Web Applications and APIs</a></li>
<li><a href="https://machinalis.com/blog/full-text-search-on-django-rest-framework/">Full Text Search in Django REST Framework with Database Backends</a></li>
<li><a href="https://machinalis.com/blog/oauth2-authentication/">OAuth2 Authentication with Django REST Framework and Custom Third-Party OAuth2 Backends</a></li>
<li><a href="https://machinalis.com/blog/nested-resources-with-django/">Nested Resources with Django REST Framework</a></li>
<li><a href="https://machinalis.com/blog/image-fields-with-django-rest-framework/">Image Fields with Django REST Framework</a></li>
<li><a href="https://chatbotslife.com/chatbot-using-django-rest-framework-api-ai-slack-part-1-3-69c7e38b7b1e#.g2aceuncf">Chatbot Using Django REST Framework + api.ai + Slack — Part 1/3</a></li>
<li><a href="https://blog.levit.be/new-django-admin-with-emberjs-what-are-the-news/">New Django Admin with DRF and EmberJS... What are the News?</a></li>
<li><a href="https://medium.com/django-rest-framework">Blog posts about Django REST Framework</a></li>
@ -482,7 +482,7 @@
<h3 id="documentations"><a class="toclink" href="#documentations">Documentations</a></h3>
<ul>
<li><a href="http://www.cdrf.co">Classy Django REST Framework</a></li>
<li><a href="http://drf-schema-adapter.readthedocs.io/en/latest/">DRF-schema-adapter</a></li>
<li><a href="https://drf-schema-adapter.readthedocs.io/en/latest/">DRF-schema-adapter</a></li>
</ul>
<p>Want your Django REST Framework talk/tutorial/article to be added to our website? Or know of a resource that's not yet included here? Please <a href="https://github.com/encode/django-rest-framework">submit a pull request</a> or <a href="mailto:anna@django-rest-framework.org">email us</a>!</p>

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

@ -446,7 +446,7 @@
<p>This tutorial will cover creating a simple pastebin code highlighting Web API. Along the way it will introduce the various components that make up REST framework, and give you a comprehensive understanding of how everything fits together.</p>
<p>The tutorial is fairly in-depth, so you should probably get a cookie and a cup of your favorite brew before getting started. If you just want a quick overview, you should head over to the <a href="../quickstart/">quickstart</a> documentation instead.</p>
<hr />
<p><strong>Note</strong>: The code for this tutorial is available in the <a href="https://github.com/encode/rest-framework-tutorial">tomchristie/rest-framework-tutorial</a> repository on GitHub. The completed implementation is also online as a sandbox version for testing, <a href="http://restframework.herokuapp.com/">available here</a>.</p>
<p><strong>Note</strong>: The code for this tutorial is available in the <a href="https://github.com/encode/rest-framework-tutorial">tomchristie/rest-framework-tutorial</a> repository on GitHub. The completed implementation is also online as a sandbox version for testing, <a href="https://restframework.herokuapp.com/">available here</a>.</p>
<hr />
<h2 id="setting-up-a-new-environment"><a class="toclink" href="#setting-up-a-new-environment">Setting up a new environment</a></h2>
<p>Before we do anything else we'll create a new virtual environment, using <a href="http://www.virtualenv.org/en/latest/index.html">virtualenv</a>. This will make sure our package configuration is kept nicely isolated from any other projects we're working on.</p>
@ -704,7 +704,7 @@ Development server is running at http://127.0.0.1:8000/
Quit the server with CONTROL-C.
</code></pre>
<p>In another terminal window, we can test the server.</p>
<p>We can test our API using <a href="http://curl.haxx.se">curl</a> or <a href="https://github.com/jakubroztocil/httpie#installation">httpie</a>. Httpie is a user friendly http client that's written in Python. Let's install that.</p>
<p>We can test our API using <a href="https://curl.haxx.se/">curl</a> or <a href="https://github.com/jakubroztocil/httpie#installation">httpie</a>. Httpie is a user friendly http client that's written in Python. Let's install that.</p>
<p>You can install httpie using pip:</p>
<pre><code>pip install httpie
</code></pre>

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

@ -414,7 +414,7 @@
<h1 id="tutorial-3-class-based-views"><a class="toclink" href="#tutorial-3-class-based-views">Tutorial 3: Class-based Views</a></h1>
<p>We can also write our API views using class-based views, rather than function based views. As we'll see this is a powerful pattern that allows us to reuse common functionality, and helps us keep our code <a href="http://en.wikipedia.org/wiki/Don't_repeat_yourself">DRY</a>.</p>
<p>We can also write our API views using class-based views, rather than function based views. As we'll see this is a powerful pattern that allows us to reuse common functionality, and helps us keep our code <a href="https://en.wikipedia.org/wiki/Don't_repeat_yourself">DRY</a>.</p>
<h2 id="rewriting-our-api-using-class-based-views"><a class="toclink" href="#rewriting-our-api-using-class-based-views">Rewriting our API using class-based views</a></h2>
<p>We'll start by rewriting the root view as a class-based view. All this involves is a little bit of refactoring of <code>views.py</code>.</p>
<pre><code>from snippets.models import Snippet

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

@ -546,7 +546,7 @@ url(r'^users/(?P&lt;pk&gt;[0-9]+)/$', views.UserDetail.as_view()),
</code></pre>
<p>And, at the end of the file, add a pattern to include the login and logout views for the browsable API.</p>
<pre><code>urlpatterns += [
url(r'^api-auth/', include('rest_framework.urls'),
url(r'^api-auth/', include('rest_framework.urls')),
]
</code></pre>
<p>The <code>r'^api-auth/'</code> part of pattern can actually be whatever URL you want to use.</p>

2
tutorial/7-schemas-and-client-libraries/index.html
View File

@ -598,7 +598,7 @@ client libraries you'll need to refer to the full documentation.</p>
<h2 id="reviewing-our-work"><a class="toclink" href="#reviewing-our-work">Reviewing our work</a></h2>
<p>With an incredibly small amount of code, we've now got a complete pastebin Web API, which is fully web browsable, includes a schema-driven client library, and comes complete with authentication, per-object permissions, and multiple renderer formats.</p>
<p>We've walked through each step of the design process, and seen how if we need to customize anything we can gradually work our way down to simply using regular Django views.</p>
<p>You can review the final <a href="https://github.com/encode/rest-framework-tutorial">tutorial code</a> on GitHub, or try out a live example in <a href="http://restframework.herokuapp.com/">the sandbox</a>.</p>
<p>You can review the final <a href="https://github.com/encode/rest-framework-tutorial">tutorial code</a> on GitHub, or try out a live example in <a href="https://restframework.herokuapp.com/">the sandbox</a>.</p>
<h2 id="onwards-and-upwards"><a class="toclink" href="#onwards-and-upwards">Onwards and upwards</a></h2>
<p>We've reached the end of our tutorial. If you want to get more involved in the REST framework project, here are a few places you can start:</p>
<ul>