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

Deployed ddfb9672 with MkDocs version: 1.0.4

Browse Source
This commit is contained in:
Tom Christie 2020-03-04 13:32:20 +00:00
parent 9d6bc0f1c3
commit 76fa169a15
20 changed files with 350 additions and 136 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
404.html
View File

@ -5,17 +5,17 @@
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta charset="utf-8">
<title>Django REST framework</title>
<link href="//img/favicon.ico" rel="icon" type="image/x-icon">
<link href="/img/favicon.ico" rel="icon" type="image/x-icon">
<link rel="canonical" href="/." />
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="description" content="Django, API, REST">
<meta name="author" content="Tom Christie">
<!-- Le styles -->
<link href="//css/prettify.css" rel="stylesheet">
<link href="//css/bootstrap.css" rel="stylesheet">
<link href="//css/bootstrap-responsive.css" rel="stylesheet">
<link href="//css/default.css" rel="stylesheet">
<link href="/css/prettify.css" rel="stylesheet">
<link href="/css/bootstrap.css" rel="stylesheet">
<link href="/css/bootstrap-responsive.css" rel="stylesheet">
<link href="/css/default.css" rel="stylesheet">
<!-- Le HTML5 shim, for IE6-8 support of HTML5 elements -->
<!--[if lt IE 9]>
@ -406,7 +406,7 @@
<div class="promo">
<hr/>
<div id="sidebarInclude">
</div>
</ul>
@ -419,7 +419,7 @@
<h1 id="404-page-not-found" style="text-align: center">404</h1>
<p style="text-align: center"><strong>Page not found</strong></p>
<p style="text-align: center">Try the <a href="https://www.django-rest-framework.org/">homepage</a>, or <a href="#searchModal" data-toggle="modal">search the documentation</a>.</p>
<p style="text-align: center">Try the <a href="/">homepage</a>, or <a href="#mkdocs_search_modal" data-toggle="modal">search the documentation</a>.</p>
@ -439,10 +439,10 @@
================================================== -->
<!-- Placed at the end of the document so the pages load faster -->
<script async src="https://fund.django-rest-framework.org/sidebar_include.js"></script>
<script src="//js/jquery-1.8.1-min.js"></script>
<script src="//js/prettify-1.0.js"></script>
<script src="//js/bootstrap-2.1.1-min.js"></script>
<script src="//js/theme.js"></script>
<script src="/js/jquery-1.8.1-min.js"></script>
<script src="/js/prettify-1.0.js"></script>
<script src="/js/bootstrap-2.1.1-min.js"></script>
<script src="/js/theme.js"></script>
<script>var base_url = '/';</script>

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

@ -1041,7 +1041,6 @@ class UserSerializer(serializers.ModelSerializer):
<p>If you want to create a custom field, you'll need to subclass <code>Field</code> and then override either one or both of the <code>.to_representation()</code> and <code>.to_internal_value()</code> methods. These two methods are used to convert between the initial datatype, and a primitive, serializable datatype. Primitive datatypes will typically be any of a number, string, boolean, <code>date</code>/<code>time</code>/<code>datetime</code> or <code>None</code>. They may also be any list or dictionary like object that only contains other primitive objects. Other types might be supported, depending on the renderer that you are using.</p>
<p>The <code>.to_representation()</code> method is called to convert the initial datatype into a primitive, serializable datatype.</p>
<p>The <code>to_internal_value()</code> method is called to restore a primitive datatype into its internal python representation. This method should raise a <code>serializers.ValidationError</code> if the data is invalid.</p>
<p>Note that the <code>WritableField</code> class that was present in version 2.x no longer exists. You should subclass <code>Field</code> and override <code>to_internal_value()</code> if the field supports data input.</p>
<h2 id="examples"><a class="toclink" href="#examples">Examples</a></h2>
<h3 id="a-basic-custom-field"><a class="toclink" href="#a-basic-custom-field">A Basic Custom Field</a></h3>
<p>Let's look at an example of serializing a class that represents an RGB color value:</p>

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

@ -679,7 +679,7 @@ class UserListView(generics.ListAPIView):
<ul>
<li>'^' Starts-with search.</li>
<li>'=' Exact matches.</li>
<li>'@' Full-text search. (Currently only supported Django's MySQL backend.)</li>
<li>'@' Full-text search. (Currently only supported Django's <a href="https://docs.djangoproject.com/en/dev/ref/contrib/postgres/search/">PostgreSQL backend</a>.)</li>
<li>'$' Regex search.</li>
</ul>
<p>For example:</p>

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

@ -678,7 +678,6 @@ class UserList(generics.ListCreateAPIView):
raise ValidationError('You have already signed up')
serializer.save(user=self.request.user)
</code></pre>
<p><strong>Note</strong>: These methods replace the old-style version 2.x <code>pre_save</code>, <code>post_save</code>, <code>pre_delete</code> and <code>post_delete</code> methods, which are no longer available.</p>
<p><strong>Other methods</strong>:</p>
<p>You won't typically need to override the following methods, although you might need to call into them if you're writing custom views using <code>GenericAPIView</code>.</p>
<ul>

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

@ -449,14 +449,16 @@ can interact with your API.</p>
<p>Django REST Framework provides support for automatic generation of
<a href="https://github.com/OAI/OpenAPI-Specification">OpenAPI</a> schemas.</p>
<h2 id="generating-an-openapi-schema"><a class="toclink" href="#generating-an-openapi-schema">Generating an OpenAPI Schema</a></h2>
<h3 id="install-pyyaml"><a class="toclink" href="#install-pyyaml">Install <code>pyyaml</code></a></h3>
<p>You'll need to install <code>pyyaml</code>, so that you can render your generated schema
into the commonly used YAML-based OpenAPI format.</p>
<pre><code>pip install pyyaml
<h3 id="install-dependencies"><a class="toclink" href="#install-dependencies">Install dependencies</a></h3>
<pre><code>pip install pyyaml uritemplate
</code></pre>
<ul>
<li><code>pyyaml</code> is used to generate schema into YAML-based OpenAPI format.</li>
<li><code>uritemplate</code> is used internally to get parameters in path.</li>
</ul>
<h3 id="generating-a-static-schema-with-the-generateschema-management-command"><a class="toclink" href="#generating-a-static-schema-with-the-generateschema-management-command">Generating a static schema with the <code>generateschema</code> management command</a></h3>
<p>If your schema is static, you can use the <code>generateschema</code> management command:</p>
<pre><code class="bash">./manage.py generateschema &gt; openapi-schema.yml
<pre><code class="bash">./manage.py generateschema --file openapi-schema.yml
</code></pre>
<p>Once you've generated a schema in this way you can annotate it with any
@ -542,7 +544,7 @@ schema_view = get_schema_view(
<p>You may customize schema generation at the level of the schema as a whole, or
on a per-view basis.</p>
<h3 id="schema-level-customization"><a class="toclink" href="#schema-level-customization">Schema Level Customization</a></h3>
<p>In order to customize the top-level schema sublass
<p>In order to customize the top-level schema subclass
<code>rest_framework.schemas.openapi.SchemaGenerator</code> and provide it as an argument
to the <code>generateschema</code> command or <code>get_schema_view()</code> helper function.</p>
<h4 id="schemagenerator"><a class="toclink" href="#schemagenerator">SchemaGenerator</a></h4>
@ -616,6 +618,185 @@ provide richer path field descriptions. (The key hooks here are the relevant
</code></pre>
<p>If you wish to provide a base <code>AutoSchema</code> subclass to be used throughout your
project you may adjust <code>settings.DEFAULT_SCHEMA_CLASS</code> appropriately.</p>
<h3 id="grouping-operations-with-tags"><a class="toclink" href="#grouping-operations-with-tags">Grouping Operations With Tags</a></h3>
<p>Tags can be used to group logical operations. Each tag name in the list MUST be unique. </p>
<hr />
<h4 id="django-rest-framework-generates-tags-automatically-with-the-following-logic"><a class="toclink" href="#django-rest-framework-generates-tags-automatically-with-the-following-logic">Django REST Framework generates tags automatically with the following logic:</a></h4>
<p>Tag name will be first element from the path. Also, any <code>_</code> in path name will be replaced by a <code>-</code>.
Consider below examples.</p>
<p>Example 1: Consider a user management system. The following table will illustrate the tag generation logic.
Here first element from the paths is: <code>users</code>. Hence tag wil be <code>users</code></p>
<table>
<thead>
<tr>
<th>Http Method</th>
<th>Path</th>
<th>Tags</th>
</tr>
</thead>
<tbody>
<tr>
<td>PUT, PATCH, GET(Retrieve), DELETE</td>
<td>/users/{id}/</td>
<td>['users']</td>
</tr>
<tr>
<td>POST, GET(List)</td>
<td>/users/</td>
<td>['users']</td>
</tr>
</tbody>
</table>
<p>Example 2: Consider a restaurant management system. The System has restaurants. Each restaurant has branches.
Consider REST APIs to deal with a branch of a particular restaurant.
Here first element from the paths is: <code>restaurants</code>. Hence tag wil be <code>restaurants</code>.</p>
<table>
<thead>
<tr>
<th>Http Method</th>
<th>Path</th>
<th>Tags</th>
</tr>
</thead>
<tbody>
<tr>
<td>PUT, PATCH, GET(Retrieve), DELETE:</td>
<td>/restaurants/{restaurant_id}/branches/{branch_id}</td>
<td>['restaurants']</td>
</tr>
<tr>
<td>POST, GET(List):</td>
<td>/restaurants/{restaurant_id}/branches/</td>
<td>['restaurants']</td>
</tr>
</tbody>
</table>
<p>Example 3: Consider Order items for an e commerce company.</p>
<table>
<thead>
<tr>
<th>Http Method</th>
<th>Path</th>
<th>Tags</th>
</tr>
</thead>
<tbody>
<tr>
<td>PUT, PATCH, GET(Retrieve), DELETE</td>
<td>/order_items/{id}/</td>
<td>['order-items']</td>
</tr>
<tr>
<td>POST, GET(List)</td>
<td>/order_items/</td>
<td>['order-items']</td>
</tr>
</tbody>
</table>
<hr />
<h4 id="overriding-auto-generated-tags"><a class="toclink" href="#overriding-auto-generated-tags">Overriding auto generated tags:</a></h4>
<p>You can override auto-generated tags by passing <code>tags</code> argument to the constructor of <code>AutoSchema</code>. <code>tags</code> argument must be a list or tuple of string.</p>
<pre><code class="python">from rest_framework.schemas.openapi import AutoSchema
from rest_framework.views import APIView
class MyView(APIView):
schema = AutoSchema(tags=['tag1', 'tag2'])
...
</code></pre>
<p>If you need more customization, you can override the <code>get_tags</code> method of <code>AutoSchema</code> class. Consider the following example:</p>
<pre><code class="python">from rest_framework.schemas.openapi import AutoSchema
from rest_framework.views import APIView
class MySchema(AutoSchema):
...
def get_tags(self, path, method):
if method == 'POST':
tags = ['tag1', 'tag2']
elif method == 'GET':
tags = ['tag2', 'tag3']
elif path == '/example/path/':
tags = ['tag3', 'tag4']
else:
tags = ['tag5', 'tag6', 'tag7']
return tags
class MyView(APIView):
schema = MySchema()
...
</code></pre>
<h3 id="operationid"><a class="toclink" href="#operationid">OperationId</a></h3>
<p>The schema generator generates an <a href="openapi-operationid">operationid</a> for each operation. This <code>operationId</code> is deduced from the model name, serializer name or view name. The operationId may looks like "listItems", "retrieveItem", "updateItem", etc..
The <code>operationId</code> is camelCase by convention.</p>
<p>If you have several views with the same model, the generator may generate duplicate operationId.
In order to work around this, you can override the second part of the operationId: operation name.</p>
<pre><code class="python">from rest_framework.schemas.openapi import AutoSchema
class ExampleView(APIView):
&quot;&quot;&quot;APIView subclass with custom schema introspection.&quot;&quot;&quot;
schema = AutoSchema(operation_id_base=&quot;Custom&quot;)
</code></pre>
<p>The previous example will generate the following operationId: "listCustoms", "retrieveCustom", "updateCustom", "partialUpdateCustom", "destroyCustom".
You need to provide the singular form of he operation name. For the list operation, a "s" will be appended at the end of the operation.</p>
<p>If you need more configuration over the <code>operationId</code> field, you can override the <code>get_operation_id_base</code> and <code>get_operation_id</code> methods from the <code>AutoSchema</code> class:</p>
<pre><code class="python">class CustomSchema(AutoSchema):
def get_operation_id_base(self, path, method, action):
pass
def get_operation_id(self, path, method):
pass
class MyView(APIView):
schema = AutoSchema(component_name=&quot;Ulysses&quot;)
</code></pre>
<h3 id="components"><a class="toclink" href="#components">Components</a></h3>
<p>Since DRF 3.12, Schema uses the <a href="openapi-components">OpenAPI Components</a>. This method defines components in the schema and <a href="openapi-reference">references them</a> inside request and response objects. By default, the component's name is deduced from the Serializer's name.</p>
<p>Using OpenAPI's components provides the following advantages:
* The schema is more readable and lightweight.
* If you use the schema to generate an SDK (using <a href="openapi-generator">openapi-generator</a> or <a href="swagger-codegen">swagger-codegen</a>). The generator can name your SDK's models.</p>
<h3 id="handling-components-schema-errors"><a class="toclink" href="#handling-components-schema-errors">Handling component's schema errors</a></h3>
<p>You may get the following error while generating the schema:</p>
<pre><code>&quot;Serializer&quot; is an invalid class name for schema generation.
Serializer's class name should be unique and explicit. e.g. &quot;ItemSerializer&quot;.
</code></pre>
<p>This error occurs when the Serializer name is "Serializer". You should choose a component's name unique across your schema and different than "Serializer".</p>
<p>You may also get the following warning:</p>
<pre><code>Schema component &quot;ComponentName&quot; has been overriden with a different value.
</code></pre>
<p>This warning occurs when different components have the same name in one schema. Your component name should be unique across your project. This is likely an error that may lead to an invalid schema.</p>
<p>You have two ways to solve the previous issues:
* You can rename your serializer with a unique name and another name than "Serializer".
* You can set the <code>component_name</code> kwarg parameter of the AutoSchema constructor (see below).
* You can override the <code>get_component_name</code> method of the AutoSchema class (see below).</p>
<h4 id="set-a-custom-components-name-for-your-view"><a class="toclink" href="#set-a-custom-components-name-for-your-view">Set a custom component's name for your view</a></h4>
<p>To override the component's name in your view, you can use the <code>component_name</code> parameter of the AutoSchema constructor:</p>
<pre><code class="python">from rest_framework.schemas.openapi import AutoSchema
class MyView(APIView):
schema = AutoSchema(component_name=&quot;Ulysses&quot;)
</code></pre>
<h4 id="override-the-default-implementation"><a class="toclink" href="#override-the-default-implementation">Override the default implementation</a></h4>
<p>If you want to have more control and customization about how the schema's components are generated, you can override the <code>get_component_name</code> and <code>get_components</code> method from the AutoSchema class.</p>
<pre><code class="python">from rest_framework.schemas.openapi import AutoSchema
class CustomSchema(AutoSchema):
def get_components(self, path, method):
# Implement your custom implementation
def get_component_name(self, serializer):
# Implement your custom implementation
class CustomView(APIView):
&quot;&quot;&quot;APIView subclass with custom schema introspection.&quot;&quot;&quot;
schema = CustomSchema()
</code></pre>
</div> <!--/span-->

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

@ -906,7 +906,7 @@ serializer.errors
<pre><code> def update(self, instance, validated_data):
profile_data = validated_data.pop('profile')
# Unless the application properly enforces that this field is
# always set, the follow could raise a `DoesNotExist`, which
# always set, the following could raise a `DoesNotExist`, which
# would need to be handled.
profile = instance.profile
@ -949,8 +949,8 @@ serializer.errors
<pre><code>def create(self, validated_data):
return User.objects.create(
username=validated_data['username'],
email=validated_data['email']
is_premium_member=validated_data['profile']['is_premium_member']
email=validated_data['email'],
is_premium_member=validated_data['profile']['is_premium_member'],
has_support_contract=validated_data['profile']['has_support_contract']
)
</code></pre>

32
community/release-notes/index.html
View File

@ -421,6 +421,10 @@
<a href="#upgrading">Upgrading</a>
</li>
<li>
<a href="#311x-series">3.11.x series</a>
</li>
<li>
<a href="#310x-series">3.10.x series</a>
</li>
@ -508,8 +512,27 @@
<pre><code>pip show djangorestframework
</code></pre>
<hr />
<h2 id="311x-series"><a class="toclink" href="#311x-series">3.11.x series</a></h2>
<h3 id="3110"><a class="toclink" href="#3110">3.11.0</a></h3>
<p><strong>Date</strong>: 12th December 2019</p>
<ul>
<li>Drop <code>.set_context</code> API <a href="../3.11-announcement#validator-default-context">in favour of a <code>requires_context</code> marker</a>.</li>
<li>Changed default widget for TextField with choices to select box. <a href="https://github.com/encode/django-rest-framework/issues/6892">#6892</a></li>
<li>Supported nested writes on non-relational fields, such as JSONField. <a href="https://github.com/encode/django-rest-framework/issues/6916">#6916</a></li>
<li>Include request/response media types in OpenAPI schemas, based on configured parsers/renderers. <a href="https://github.com/encode/django-rest-framework/issues/6865">#6865</a></li>
<li>Include operation descriptions in OpenAPI schemas, based on the docstring on the view. <a href="https://github.com/encode/django-rest-framework/issues/6898">#6898</a></li>
<li>Fix representation of serializers with all optional fields in OpenAPI schemas. <a href="https://github.com/encode/django-rest-framework/issues/6941">#6941</a>, <a href="https://github.com/encode/django-rest-framework/issues/6944">#6944</a></li>
<li>Fix representation of <code>serializers.HStoreField</code> in OpenAPI schemas. <a href="https://github.com/encode/django-rest-framework/issues/6914">#6914</a></li>
<li>Fix OpenAPI generation when title or version is not provided. <a href="https://github.com/encode/django-rest-framework/issues/6912">#6912</a></li>
<li>Use <code>int64</code> representation for large integers in OpenAPI schemas. <a href="https://github.com/encode/django-rest-framework/issues/7018">#7018</a></li>
<li>Improved error messages if no <code>.to_representation</code> implementation is provided on a field subclass. <a href="https://github.com/encode/django-rest-framework/issues/6996">#6996</a></li>
<li>Fix for serializer classes that use multiple inheritance. <a href="https://github.com/encode/django-rest-framework/issues/6980">#6980</a></li>
<li>Fix for reversing Hyperlinked URL fields with percent encoded components in the path. <a href="https://github.com/encode/django-rest-framework/issues/7059">#7059</a></li>
<li>Update bootstrap to 3.4.1. <a href="https://github.com/encode/django-rest-framework/issues/6923">#6923</a></li>
</ul>
<h2 id="310x-series"><a class="toclink" href="#310x-series">3.10.x series</a></h2>
<h3 id="3103"><a class="toclink" href="#3103">3.10.3</a></h3>
<p><strong>Date</strong>: 4th September 2019</p>
<ul>
<li>Include API version in OpenAPI schema generation, defaulting to empty string.</li>
<li>Add pagination properties to OpenAPI response schemas.</li>
@ -520,12 +543,7 @@
<li>Use consistent <code>lowerInitialCamelCase</code> style in OpenAPI operation IDs.</li>
<li>Fix <code>minLength</code>/<code>maxLength</code>/<code>minItems</code>/<code>maxItems</code> properties in OpenAPI schemas.</li>
<li>Only call <code>FileField.url</code> once in serialization, for improved performance.</li>
<li>
<p>Fix an edge case where throttling calcualtions could error after a configuration change.</p>
</li>
<li>
<p>TODO</p>
</li>
<li>Fix an edge case where throttling calculations could error after a configuration change.</li>
</ul>
<h3 id="3102"><a class="toclink" href="#3102">3.10.2</a></h3>
<p><strong>Date</strong>: 29th July 2019</p>
@ -1645,6 +1663,8 @@ Previously may have been stored internally as <code>None</code>.</p>
<!-- 3.9.3 -->
<!-- 3.10.0 -->
<!-- 3.11.0 -->
</div> <!--/span-->

1
community/third-party-packages/index.html
View File

@ -644,6 +644,7 @@ You probably want to also tag the version now:
<li><a href="https://github.com/jozo/django-rest-framework-condition">django-rest-framework-condition</a> - Decorators for managing HTTP cache headers for Django REST framework (ETag and Last-modified).</li>
<li><a href="https://github.com/shosca/django-rest-witchcraft">django-rest-witchcraft</a> - Provides DRF integration with SQLAlchemy with SQLAlchemy model serializers/viewsets and a bunch of other goodies</li>
<li><a href="https://github.com/corteva/djangorestframework-mvt">djangorestframework-mvt</a> - An extension for creating views that serve Postgres data as Map Box Vector Tiles.</li>
<li><a href="https://github.com/fvlima/drf-viewset-profiler">drf-viewset-profiler</a> - Lib to profile all methods from a viewset line by line.</li>
<li><a href="https://github.com/cloudcode-hungary/django-rest-framework-features/">djangorestframework-features</a> - Advanced schema generation and more based on named features.</li>
</ul>

4
community/tutorials-and-resources/index.html
View File

@ -450,8 +450,8 @@
<a class="book-cover" href="https://www.twoscoopspress.com/products/two-scoops-of-django-1-11">
<img src="../../img/books/tsd-cover.png"/>
</a>
<a class="book-cover" href="https://wsvincent.com/books/">
<img src="../../img/books/rad-cover.png"/>
<a class="book-cover" href="https://djangoforapis.com">
<img src="../../img/books/dfa-cover.jpg"/>
</a>
<a class="book-cover" href="https://books.agiliq.com/projects/django-api-polls-tutorial/en/latest/">
<img src="../../img/books/bda-cover.png"/>

7
css/default.css
View File

@ -74,6 +74,12 @@ pre {
white-space: pre;
}
code, pre {
font-family: Consolas,Menlo,Monaco,Lucida Console,Liberation Mono,DejaVu Sans Mono,Bitstream Vera Sans Mono,Courier New,monospace,sans-serif;
font-size: 13px;
}
/* Preserve the spacing of the navbar across different screen sizes. */
.navbar-inner {
/*padding: 5px 0;*/
@ -432,3 +438,4 @@ ul.sponsor {
margin: 0 !important;
display: inline-block !important;
}

BIN
img/books/dfa-cover.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 49 KiB

BIN
img/books/rad-cover.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 14 KiB

18
index.html
View File

@ -5,17 +5,17 @@
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta charset="utf-8">
<title>Home - Django REST framework</title>
<link href="./img/favicon.ico" rel="icon" type="image/x-icon">
<link href="img/favicon.ico" rel="icon" type="image/x-icon">
<link rel="canonical" href="https://www.django-rest-framework.org/" />
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="description" content="Django, API, REST, Home">
<meta name="author" content="Tom Christie">
<!-- Le styles -->
<link href="./css/prettify.css" rel="stylesheet">
<link href="./css/bootstrap.css" rel="stylesheet">
<link href="./css/bootstrap-responsive.css" rel="stylesheet">
<link href="./css/default.css" rel="stylesheet">
<link href="css/prettify.css" rel="stylesheet">
<link href="css/bootstrap.css" rel="stylesheet">
<link href="css/bootstrap-responsive.css" rel="stylesheet">
<link href="css/default.css" rel="stylesheet">
<!-- Le HTML5 shim, for IE6-8 support of HTML5 elements -->
<!--[if lt IE 9]>
@ -696,10 +696,10 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.</p>
================================================== -->
<!-- Placed at the end of the document so the pages load faster -->
<script async src="https://fund.django-rest-framework.org/sidebar_include.js"></script>
<script src="./js/jquery-1.8.1-min.js"></script>
<script src="./js/prettify-1.0.js"></script>
<script src="./js/bootstrap-2.1.1-min.js"></script>
<script src="./js/theme.js"></script>
<script src="js/jquery-1.8.1-min.js"></script>
<script src="js/prettify-1.0.js"></script>
<script src="js/bootstrap-2.1.1-min.js"></script>
<script src="js/theme.js"></script>
<script>var base_url = '.';</script>

2
search/search_index.json
View File

File diff suppressed because one or more lines are too long

130
sitemap.xml
View File

@ -2,327 +2,327 @@
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
<url>
<loc>https://www.django-rest-framework.org/</loc>
<lastmod>2019-12-12</lastmod>
<lastmod>2020-03-04</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>https://www.django-rest-framework.org/tutorial/quickstart/</loc>
<lastmod>2019-12-12</lastmod>
<lastmod>2020-03-04</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>https://www.django-rest-framework.org/tutorial/1-serialization/</loc>
<lastmod>2019-12-12</lastmod>
<lastmod>2020-03-04</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>https://www.django-rest-framework.org/tutorial/2-requests-and-responses/</loc>
<lastmod>2019-12-12</lastmod>
<lastmod>2020-03-04</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>https://www.django-rest-framework.org/tutorial/3-class-based-views/</loc>
<lastmod>2019-12-12</lastmod>
<lastmod>2020-03-04</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>https://www.django-rest-framework.org/tutorial/4-authentication-and-permissions/</loc>
<lastmod>2019-12-12</lastmod>
<lastmod>2020-03-04</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>https://www.django-rest-framework.org/tutorial/5-relationships-and-hyperlinked-apis/</loc>
<lastmod>2019-12-12</lastmod>
<lastmod>2020-03-04</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>https://www.django-rest-framework.org/tutorial/6-viewsets-and-routers/</loc>
<lastmod>2019-12-12</lastmod>
<lastmod>2020-03-04</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>https://www.django-rest-framework.org/api-guide/requests/</loc>
<lastmod>2019-12-12</lastmod>
<lastmod>2020-03-04</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>https://www.django-rest-framework.org/api-guide/responses/</loc>
<lastmod>2019-12-12</lastmod>
<lastmod>2020-03-04</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>https://www.django-rest-framework.org/api-guide/views/</loc>
<lastmod>2019-12-12</lastmod>
<lastmod>2020-03-04</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>https://www.django-rest-framework.org/api-guide/generic-views/</loc>
<lastmod>2019-12-12</lastmod>
<lastmod>2020-03-04</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>https://www.django-rest-framework.org/api-guide/viewsets/</loc>
<lastmod>2019-12-12</lastmod>
<lastmod>2020-03-04</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>https://www.django-rest-framework.org/api-guide/routers/</loc>
<lastmod>2019-12-12</lastmod>
<lastmod>2020-03-04</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>https://www.django-rest-framework.org/api-guide/parsers/</loc>
<lastmod>2019-12-12</lastmod>
<lastmod>2020-03-04</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>https://www.django-rest-framework.org/api-guide/renderers/</loc>
<lastmod>2019-12-12</lastmod>
<lastmod>2020-03-04</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>https://www.django-rest-framework.org/api-guide/serializers/</loc>
<lastmod>2019-12-12</lastmod>
<lastmod>2020-03-04</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>https://www.django-rest-framework.org/api-guide/fields/</loc>
<lastmod>2019-12-12</lastmod>
<lastmod>2020-03-04</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>https://www.django-rest-framework.org/api-guide/relations/</loc>
<lastmod>2019-12-12</lastmod>
<lastmod>2020-03-04</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>https://www.django-rest-framework.org/api-guide/validators/</loc>
<lastmod>2019-12-12</lastmod>
<lastmod>2020-03-04</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>https://www.django-rest-framework.org/api-guide/authentication/</loc>
<lastmod>2019-12-12</lastmod>
<lastmod>2020-03-04</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>https://www.django-rest-framework.org/api-guide/permissions/</loc>
<lastmod>2019-12-12</lastmod>
<lastmod>2020-03-04</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>https://www.django-rest-framework.org/api-guide/caching/</loc>
<lastmod>2019-12-12</lastmod>
<lastmod>2020-03-04</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>https://www.django-rest-framework.org/api-guide/throttling/</loc>
<lastmod>2019-12-12</lastmod>
<lastmod>2020-03-04</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>https://www.django-rest-framework.org/api-guide/filtering/</loc>
<lastmod>2019-12-12</lastmod>
<lastmod>2020-03-04</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>https://www.django-rest-framework.org/api-guide/pagination/</loc>
<lastmod>2019-12-12</lastmod>
<lastmod>2020-03-04</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>https://www.django-rest-framework.org/api-guide/versioning/</loc>
<lastmod>2019-12-12</lastmod>
<lastmod>2020-03-04</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>https://www.django-rest-framework.org/api-guide/content-negotiation/</loc>
<lastmod>2019-12-12</lastmod>
<lastmod>2020-03-04</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>https://www.django-rest-framework.org/api-guide/metadata/</loc>
<lastmod>2019-12-12</lastmod>
<lastmod>2020-03-04</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>https://www.django-rest-framework.org/api-guide/schemas/</loc>
<lastmod>2019-12-12</lastmod>
<lastmod>2020-03-04</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>https://www.django-rest-framework.org/api-guide/format-suffixes/</loc>
<lastmod>2019-12-12</lastmod>
<lastmod>2020-03-04</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>https://www.django-rest-framework.org/api-guide/reverse/</loc>
<lastmod>2019-12-12</lastmod>
<lastmod>2020-03-04</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>https://www.django-rest-framework.org/api-guide/exceptions/</loc>
<lastmod>2019-12-12</lastmod>
<lastmod>2020-03-04</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>https://www.django-rest-framework.org/api-guide/status-codes/</loc>
<lastmod>2019-12-12</lastmod>
<lastmod>2020-03-04</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>https://www.django-rest-framework.org/api-guide/testing/</loc>
<lastmod>2019-12-12</lastmod>
<lastmod>2020-03-04</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>https://www.django-rest-framework.org/api-guide/settings/</loc>
<lastmod>2019-12-12</lastmod>
<lastmod>2020-03-04</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>https://www.django-rest-framework.org/topics/documenting-your-api/</loc>
<lastmod>2019-12-12</lastmod>
<lastmod>2020-03-04</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>https://www.django-rest-framework.org/topics/api-clients/</loc>
<lastmod>2019-12-12</lastmod>
<lastmod>2020-03-04</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>https://www.django-rest-framework.org/topics/internationalization/</loc>
<lastmod>2019-12-12</lastmod>
<lastmod>2020-03-04</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>https://www.django-rest-framework.org/topics/ajax-csrf-cors/</loc>
<lastmod>2019-12-12</lastmod>
<lastmod>2020-03-04</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>https://www.django-rest-framework.org/topics/html-and-forms/</loc>
<lastmod>2019-12-12</lastmod>
<lastmod>2020-03-04</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>https://www.django-rest-framework.org/topics/browser-enhancements/</loc>
<lastmod>2019-12-12</lastmod>
<lastmod>2020-03-04</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>https://www.django-rest-framework.org/topics/browsable-api/</loc>
<lastmod>2019-12-12</lastmod>
<lastmod>2020-03-04</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>https://www.django-rest-framework.org/topics/rest-hypermedia-hateoas/</loc>
<lastmod>2019-12-12</lastmod>
<lastmod>2020-03-04</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>https://www.django-rest-framework.org/community/tutorials-and-resources/</loc>
<lastmod>2019-12-12</lastmod>
<lastmod>2020-03-04</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>https://www.django-rest-framework.org/community/third-party-packages/</loc>
<lastmod>2019-12-12</lastmod>
<lastmod>2020-03-04</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>https://www.django-rest-framework.org/community/contributing/</loc>
<lastmod>2019-12-12</lastmod>
<lastmod>2020-03-04</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>https://www.django-rest-framework.org/community/project-management/</loc>
<lastmod>2019-12-12</lastmod>
<lastmod>2020-03-04</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>https://www.django-rest-framework.org/community/release-notes/</loc>
<lastmod>2019-12-12</lastmod>
<lastmod>2020-03-04</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>https://www.django-rest-framework.org/community/3.11-announcement/</loc>
<lastmod>2019-12-12</lastmod>
<lastmod>2020-03-04</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>https://www.django-rest-framework.org/community/3.10-announcement/</loc>
<lastmod>2019-12-12</lastmod>
<lastmod>2020-03-04</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>https://www.django-rest-framework.org/community/3.9-announcement/</loc>
<lastmod>2019-12-12</lastmod>
<lastmod>2020-03-04</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>https://www.django-rest-framework.org/community/3.8-announcement/</loc>
<lastmod>2019-12-12</lastmod>
<lastmod>2020-03-04</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>https://www.django-rest-framework.org/community/3.7-announcement/</loc>
<lastmod>2019-12-12</lastmod>
<lastmod>2020-03-04</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>https://www.django-rest-framework.org/community/3.6-announcement/</loc>
<lastmod>2019-12-12</lastmod>
<lastmod>2020-03-04</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>https://www.django-rest-framework.org/community/3.5-announcement/</loc>
<lastmod>2019-12-12</lastmod>
<lastmod>2020-03-04</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>https://www.django-rest-framework.org/community/3.4-announcement/</loc>
<lastmod>2019-12-12</lastmod>
<lastmod>2020-03-04</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>https://www.django-rest-framework.org/community/3.3-announcement/</loc>
<lastmod>2019-12-12</lastmod>
<lastmod>2020-03-04</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>https://www.django-rest-framework.org/community/3.2-announcement/</loc>
<lastmod>2019-12-12</lastmod>
<lastmod>2020-03-04</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>https://www.django-rest-framework.org/community/3.1-announcement/</loc>
<lastmod>2019-12-12</lastmod>
<lastmod>2020-03-04</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>https://www.django-rest-framework.org/community/3.0-announcement/</loc>
<lastmod>2019-12-12</lastmod>
<lastmod>2020-03-04</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>https://www.django-rest-framework.org/community/kickstarter-announcement/</loc>
<lastmod>2019-12-12</lastmod>
<lastmod>2020-03-04</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>https://www.django-rest-framework.org/community/mozilla-grant/</loc>
<lastmod>2019-12-12</lastmod>
<lastmod>2020-03-04</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>https://www.django-rest-framework.org/community/funding/</loc>
<lastmod>2019-12-12</lastmod>
<lastmod>2020-03-04</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>https://www.django-rest-framework.org/community/jobs/</loc>
<lastmod>2019-12-12</lastmod>
<lastmod>2020-03-04</lastmod>
<changefreq>daily</changefreq>
</url>
</urlset>

BIN
sitemap.xml.gz
View File

Binary file not shown.

54
topics/api-clients/index.html
View File

@ -797,7 +797,7 @@ that modify the outgoing requests.</p>
urlpatterns = [
...
url(r'^docs/', include_docs_urls(title='My API service'))
url(r'^docs/', include_docs_urls(title='My API service'), name='api-docs'),
]
</code></pre>
<p>Once the API documentation URLs are installed, you'll be able to include both the required JavaScript resources. Note that the ordering of these two lines is important, as the schema loading requires CoreAPI to already be installed.</p>
@ -812,12 +812,12 @@ urlpatterns = [
&lt;script src="{% url 'api-docs:schema-js' %}"&gt;&lt;/script&gt;
</code></pre>
<p>The <code>coreapi</code> library, and the <code>schema</code> object will now both be available on the <code>window</code> instance.</p>
<pre><code>const coreapi = window.coreapi
const schema = window.schema
<pre><code>const coreapi = window.coreapi;
const schema = window.schema;
</code></pre>
<h2 id="instantiating-a-client"><a class="toclink" href="#instantiating-a-client">Instantiating a client</a></h2>
<p>In order to interact with the API you'll need a client instance.</p>
<pre><code>var client = new coreapi.Client()
<pre><code>var client = new coreapi.Client();
</code></pre>
<p>Typically you'll also want to provide some authentication credentials when
instantiating the client.</p>
@ -827,9 +827,9 @@ authentication. You'll want to provide a standard HTML login flow, to allow
the user to login, and then instantiate a client using session authentication:</p>
<pre><code>let auth = new coreapi.auth.SessionAuthentication({
csrfCookieName: 'csrftoken',
csrfHeaderName: 'X-CSRFToken'
})
let client = new coreapi.Client({auth: auth})
csrfHeaderName: 'X-CSRFToken',
});
let client = new coreapi.Client({auth: auth});
</code></pre>
<p>The authentication scheme will handle including a CSRF header in any outgoing
requests for unsafe HTTP methods.</p>
@ -837,10 +837,10 @@ requests for unsafe HTTP methods.</p>
<p>The <code>TokenAuthentication</code> class can be used to support REST framework's built-in
<code>TokenAuthentication</code>, as well as OAuth and JWT schemes.</p>
<pre><code>let auth = new coreapi.auth.TokenAuthentication({
scheme: 'JWT'
token: '&lt;token&gt;'
})
let client = new coreapi.Client({auth: auth})
scheme: 'JWT',
token: '&lt;token&gt;',
});
let client = new coreapi.Client({auth: auth});
</code></pre>
<p>When using TokenAuthentication you'll probably need to implement a login flow
using the CoreAPI client.</p>
@ -848,20 +848,20 @@ using the CoreAPI client.</p>
request to an "obtain token" endpoint</p>
<p>For example, using the "Django REST framework JWT" package</p>
<pre><code>// Setup some globally accessible state
window.client = new coreapi.Client()
window.loggedIn = false
window.client = new coreapi.Client();
window.loggedIn = false;
function loginUser(username, password) {
let action = ["api-token-auth", "obtain-token"]
let params = {username: "example", email: "example@example.com"}
let action = ["api-token-auth", "obtain-token"];
let params = {username: "example", email: "example@example.com"};
client.action(schema, action, params).then(function(result) {
// On success, instantiate an authenticated client.
let auth = window.coreapi.auth.TokenAuthentication({
scheme: 'JWT',
token: result['token']
token: result['token'],
})
window.client = coreapi.Client({auth: auth})
window.loggedIn = true
window.client = coreapi.Client({auth: auth});
window.loggedIn = true;
}).catch(function (error) {
// Handle error case where eg. user provides incorrect credentials.
})
@ -871,20 +871,20 @@ function loginUser(username, password) {
<p>The <code>BasicAuthentication</code> class can be used to support HTTP Basic Authentication.</p>
<pre><code>let auth = new coreapi.auth.BasicAuthentication({
username: '&lt;username&gt;',
password: '&lt;password&gt;'
password: '&lt;password&gt;',
})
let client = new coreapi.Client({auth: auth})
let client = new coreapi.Client({auth: auth});
</code></pre>
<h2 id="using-the-client"><a class="toclink" href="#using-the-client">Using the client</a></h2>
<p>Making requests:</p>
<pre><code>let action = ["users", "list"]
<pre><code>let action = ["users", "list"];
client.action(schema, action).then(function(result) {
// Return value is in 'result'
})
</code></pre>
<p>Including parameters:</p>
<pre><code>let action = ["users", "create"]
let params = {username: "example", email: "example@example.com"}
<pre><code>let action = ["users", "create"];
let params = {username: "example", email: "example@example.com"};
client.action(schema, action, params).then(function(result) {
// Return value is in 'result'
})
@ -903,12 +903,12 @@ $ node
const coreapi = require('coreapi')
</code></pre>
<p>You'll either want to include the API schema in your codebase directly, by copying it from the <code>schema.js</code> resource, or else load the schema asynchronously. For example:</p>
<pre><code>let client = new coreapi.Client()
let schema = null
<pre><code>let client = new coreapi.Client();
let schema = null;
client.get("https://api.example.org/").then(function(data) {
// Load a CoreJSON API schema.
schema = data
console.log('schema loaded')
schema = data;
console.log('schema loaded');
})
</code></pre>

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

@ -477,7 +477,11 @@ this:</p>
SwaggerUIBundle.presets.apis,
SwaggerUIBundle.SwaggerUIStandalonePreset
],
layout: &quot;BaseLayout&quot;
layout: &quot;BaseLayout&quot;,
requestInterceptor: (request) =&gt; {
request.headers['X-CSRFToken'] = &quot;{{ csrf_token }}&quot;
return request;
}
})
&lt;/script&gt;
&lt;/body&gt;

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

@ -477,7 +477,7 @@ request.data # Handles arbitrary data. Works for 'POST', 'PUT' and 'PATCH' met
<li>The <code>APIView</code> class for working with class-based views.</li>
</ol>
<p>These wrappers provide a few bits of functionality such as making sure you receive <code>Request</code> instances in your view, and adding context to <code>Response</code> objects so that content negotiation can be performed.</p>
<p>The wrappers also provide behaviour such as returning <code>405 Method Not Allowed</code> responses when appropriate, and handling any <code>ParseError</code> exception that occurs when accessing <code>request.data</code> with malformed input.</p>
<p>The wrappers also provide behaviour such as returning <code>405 Method Not Allowed</code> responses when appropriate, and handling any <code>ParseError</code> exceptions that occur when accessing <code>request.data</code> with malformed input.</p>
<h2 id="pulling-it-all-together"><a class="toclink" href="#pulling-it-all-together">Pulling it all together</a></h2>
<p>Okay, let's go ahead and start using these new components to refactor our views slightly.</p>
<pre><code>from rest_framework import status

5
tutorial/quickstart/index.html
View File

@ -525,6 +525,7 @@ class GroupSerializer(serializers.HyperlinkedModelSerializer):
<p>Right, we'd better write some views then. Open <code>tutorial/quickstart/views.py</code> and get typing.</p>
<pre><code>from django.contrib.auth.models import User, Group
from rest_framework import viewsets
from rest_framework import permissions
from tutorial.quickstart.serializers import UserSerializer, GroupSerializer
@ -534,6 +535,7 @@ class UserViewSet(viewsets.ModelViewSet):
"""
queryset = User.objects.all().order_by('-date_joined')
serializer_class = UserSerializer
permission_classes = [permissions.IsAuthenticated]
class GroupViewSet(viewsets.ModelViewSet):
@ -542,6 +544,7 @@ class GroupViewSet(viewsets.ModelViewSet):
"""
queryset = Group.objects.all()
serializer_class = GroupSerializer
permission_classes = [permissions.IsAuthenticated]
</code></pre>
<p>Rather than write multiple views we're grouping together all the common behavior into classes called <code>ViewSets</code>.</p>
<p>We can easily break these down into individual views if we need to, but using viewsets keeps the view logic nicely organized as well as being very concise.</p>
@ -636,7 +639,7 @@ HTTP/1.1 200 OK
<p><img alt="Quick start image" src="../../img/quickstart.png" /></p>
<p>If you're working through the browser, make sure to login using the control in the top right corner.</p>
<p>Great, that was easy!</p>
<p>If you want to get a more in depth understanding of how REST framework fits together head on over to <a href="../1-serialization/">the tutorial</a>, or start browsing the <a href="../#api-guide">API guide</a>.</p>
<p>If you want to get a more in depth understanding of how REST framework fits together head on over to <a href="../1-serialization/">the tutorial</a>, or start browsing the <a href="../../api-guide/requests/">API guide</a>.</p>
</div> <!--/span-->