encode/django-rest-framework
1
1
Fork 0
mirror of https://github.com/encode/django-rest-framework.git synced 2025-10-31 16:07:38 +03:00
Code Issues Packages Projects Releases Wiki Activity

Deployed ade172e with MkDocs version: 1.6.0

Browse Source
This commit is contained in:
2025-10-27 16:45:11 +00:00
parent 6827361069
commit 322f17434c
24 changed files with 60 additions and 60 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -853,7 +853,7 @@ 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 package for JWT authentication is <a href="https://github.com/davesque/django-rest-framework-simplejwt">djangorestframework-simplejwt</a> which provides some 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="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>
<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> let's 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="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> (outdated) package which provides an easy-to-use HTTP Signature Authentication mechanism. You can use the updated fork version of <a href="https://github.com/etoccalino/django-rest-framework-httpsignature">djangorestframework-httpsignature</a>, which is <a href="https://github.com/ahknight/drf-httpsig">drf-httpsig</a>.</p>
<h2 id="djoser"><a class="toclink" href="#djoser">Djoser</a></h2>

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

@ -759,7 +759,7 @@ explicitly declare the <code>BooleanField</code> on the serializer class, or use
</ul>
<p>The <code>allow_null</code> option is also available for string fields, although its usage is discouraged in favor of <code>allow_blank</code>. It is valid to set both <code>allow_blank=True</code> and <code>allow_null=True</code>, but doing so means that there will be two differing types of empty value permissible for string representations, which can lead to data inconsistencies and subtle application bugs.</p>
<h2 id="emailfield"><a class="toclink" href="#emailfield">EmailField</a></h2>
<p>A text representation, validates the text to be a valid e-mail address.</p>
<p>A text representation, validates the text to be a valid email address.</p>
<p>Corresponds to <code>django.db.models.fields.EmailField</code></p>
<p><strong>Signature:</strong> <code>EmailField(max_length=None, min_length=None, allow_blank=False)</code></p>
<h2 id="regexfield"><a class="toclink" href="#regexfield">RegexField</a></h2>
@ -1204,7 +1204,7 @@ OrderedDict([('label', 'Second Example'),
</code></pre>
</li>
</ul>
<p>For completeness lets do the same thing again but with the nested serializer
<p>For completeness let's do the same thing again but with the nested serializer
approach suggested above:</p>
<pre><code>class NestedCoordinateSerializer(serializers.Serializer):
x = serializers.IntegerField(source='x_coordinate')

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

@ -793,7 +793,7 @@ class AlbumSerializer(serializers.ModelSerializer):
fields = ['album_name', 'artist', 'tracks']
</code></pre>
<p>Would serialize to a nested representation like this:</p>
<pre><code>&gt;&gt;&gt; album = Album.objects.create(album_name="The Grey Album", artist='Danger Mouse')
<pre><code>&gt;&gt;&gt; album = Album.objects.create(album_name="The Gray Album", artist='Danger Mouse')
&gt;&gt;&gt; Track.objects.create(album=album, order=1, title='Public Service Announcement', duration=245)
&lt;Track: Track object&gt;
&gt;&gt;&gt; Track.objects.create(album=album, order=2, title='What More Can I Say', duration=264)
@ -803,7 +803,7 @@ class AlbumSerializer(serializers.ModelSerializer):
&gt;&gt;&gt; serializer = AlbumSerializer(instance=album)
&gt;&gt;&gt; serializer.data
{
'album_name': 'The Grey Album',
'album_name': 'The Gray Album',
'artist': 'Danger Mouse',
'tracks': [
{'order': 1, 'title': 'Public Service Announcement', 'duration': 245},
@ -835,7 +835,7 @@ class AlbumSerializer(serializers.ModelSerializer):
return album
&gt;&gt;&gt; data = {
'album_name': 'The Grey Album',
'album_name': 'The Gray Album',
'artist': 'Danger Mouse',
'tracks': [
{'order': 1, 'title': 'Public Service Announcement', 'duration': 245},

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

@ -679,7 +679,7 @@ Unlike other renderers, the data passed to the <code>Response</code> does not ne
return Response({'user': self.object}, template_name='user_detail.html')
</code></pre>
<p>You can use <code>TemplateHTMLRenderer</code> either to return regular HTML pages using REST framework, or to return both HTML and API responses from a single endpoint.</p>
<p>If you're building websites that use <code>TemplateHTMLRenderer</code> along with other renderer classes, you should consider listing <code>TemplateHTMLRenderer</code> as the first class in the <code>renderer_classes</code> list, so that it will be prioritised first even for browsers that send poorly formed <code>ACCEPT:</code> headers.</p>
<p>If you're building websites that use <code>TemplateHTMLRenderer</code> along with other renderer classes, you should consider listing <code>TemplateHTMLRenderer</code> as the first class in the <code>renderer_classes</code> list, so that it will be prioritized first even for browsers that send poorly formed <code>ACCEPT:</code> headers.</p>
<p>See the <a href="../../topics/html-and-forms/"><em>HTML &amp; Forms</em> Topic Page</a> for further examples of <code>TemplateHTMLRenderer</code> usage.</p>
<p><strong>.media_type</strong>: <code>text/html</code></p>
<p><strong>.format</strong>: <code>'html'</code></p>

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

@ -502,7 +502,7 @@
<p>&mdash; <a href="https://docs.djangoproject.com/en/stable/ref/template-response/">Django documentation</a></p>
</blockquote>
<p>REST framework supports HTTP content negotiation by providing a <code>Response</code> class which allows you to return content that can be rendered into multiple content types, depending on the client request.</p>
<p>The <code>Response</code> class subclasses Django's <code>SimpleTemplateResponse</code>. <code>Response</code> objects are initialised with data, which should consist of native Python primitives. REST framework then uses standard HTTP content negotiation to determine how it should render the final response content.</p>
<p>The <code>Response</code> class subclasses Django's <code>SimpleTemplateResponse</code>. <code>Response</code> objects are initialized with data, which should consist of native Python primitives. REST framework then uses standard HTTP content negotiation to determine how it should render the final response content.</p>
<p>There's no requirement for you to use the <code>Response</code> class, you can also return regular <code>HttpResponse</code> or <code>StreamingHttpResponse</code> objects from your views if required. Using the <code>Response</code> class simply provides a nicer interface for returning content-negotiated Web API responses, that can be rendered to multiple formats.</p>
<p>Unless you want to heavily customize REST framework for some reason, you should always use an <code>APIView</code> class or <code>@api_view</code> function for views that return <code>Response</code> objects. Doing so ensures that the view can perform content negotiation and select the appropriate renderer for the response, before it is returned from the view.</p>
<hr />

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

@ -471,7 +471,7 @@ functionality instead. The built-in support will be moved into a separate
package and then subsequently retired over the next releases.</p>
<p>As a full-fledged replacement, we recommend the <a href="https://drf-spectacular.readthedocs.io/en/latest/readme.html">drf-spectacular</a> package.
It has extensive support for generating OpenAPI 3 schemas from
REST framework APIs, with both automatic and customisable options available.
REST framework APIs, with both automatic and customizable options available.
For further information please refer to
<a href="../../topics/documenting-your-api/#drf-spectacular">Documenting your API</a>.</p>
<hr />

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

@ -706,7 +706,7 @@ class CommentSerializer(serializers.Serializer):
serializer.data
# {'email': 'leila@example.com', 'content': 'foo bar', 'created': '2016-01-27T15:17:10.375877'}
</code></pre>
<p>At this point we've translated the model instance into Python native datatypes. To finalise the serialization process we render the data into <code>json</code>.</p>
<p>At this point we've translated the model instance into Python native datatypes. To finalize the serialization process we render the data into <code>json</code>.</p>
<pre><code>from rest_framework.renderers import JSONRenderer
json = JSONRenderer().render(serializer.data)
@ -792,7 +792,7 @@ serializer = CommentSerializer(comment, data=data)
serializer.is_valid()
# False
serializer.errors
# {'email': ['Enter a valid e-mail address.'], 'created': ['This field is required.']}
# {'email': ['Enter a valid email address.'], 'created': ['This field is required.']}
</code></pre>
<p>Each key in the dictionary will be the field name, and the values will be lists of strings of any error messages corresponding to that field. The <code>non_field_errors</code> key may also be present, and will list any general validation errors. The name of the <code>non_field_errors</code> key may be customized using the <code>NON_FIELD_ERRORS_KEY</code> REST framework setting.</p>
<p>When deserializing a list of items, errors will be returned as a list of dictionaries representing each of the deserialized items.</p>
@ -905,7 +905,7 @@ class CommentSerializer(serializers.Serializer):
serializer.is_valid()
# False
serializer.errors
# {'user': {'email': ['Enter a valid e-mail address.']}, 'created': ['This field is required.']}
# {'user': {'email': ['Enter a valid email address.']}, 'created': ['This field is required.']}
</code></pre>
<p>Similarly, the <code>.validated_data</code> property will include nested data structures.</p>
<h4 id="writing-create-methods-for-nested-representations"><a class="toclink" href="#writing-create-methods-for-nested-representations">Writing <code>.create()</code> methods for nested representations</a></h4>
@ -1011,7 +1011,7 @@ serializer.data
<hr />
<h1 id="modelserializer"><a class="toclink" href="#modelserializer">ModelSerializer</a></h1>
<p>Often you'll want serializer classes that map closely to Django model definitions.</p>
<p>The <code>ModelSerializer</code> class provides a shortcut that lets you automatically create a <code>Serializer</code> class with fields that correspond to the Model fields.</p>
<p>The <code>ModelSerializer</code> class provides a shortcut that let's you automatically create a <code>Serializer</code> class with fields that correspond to the Model fields.</p>
<p><strong>The <code>ModelSerializer</code> class is the same as a regular <code>Serializer</code> class, except that</strong>:</p>
<ul>
<li>It will automatically generate a set of fields for you, based on the model.</li>

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

@ -752,7 +752,7 @@ assert response.status_code == 200
csrftoken = response.cookies['csrftoken']
# Interact with the API.
response = client.post('http://testserver/organisations/', json={
response = client.post('http://testserver/organizations/', json={
'name': 'MegaCorp',
'status': 'active'
}, headers={'X-CSRFToken': csrftoken})
@ -774,12 +774,12 @@ do not directly affect customer data.</p>
client = CoreAPIClient()
schema = client.get('http://testserver/schema/')
# Create a new organisation
# Create a new organization
params = {'name': 'MegaCorp', 'status': 'active'}
client.action(schema, ['organisations', 'create'], params)
client.action(schema, ['organizations', 'create'], params)
# Ensure that the organisation exists in the listing
data = client.action(schema, ['organisations', 'list'])
# Ensure that the organization exists in the listing
data = client.action(schema, ['organizations', 'list'])
assert(len(data) == 1)
assert(data == [{'name': 'MegaCorp', 'status': 'active'}])
</code></pre>

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

@ -644,7 +644,7 @@ class ExampleSerializer(serializers.Serializer):
<h1 id="advanced-field-defaults"><a class="toclink" href="#advanced-field-defaults">Advanced field defaults</a></h1>
<p>Validators that are applied across multiple fields in the serializer can sometimes require a field input that should not be provided by the API client, but that <em>is</em> available as input to the validator.
For this purposes use <code>HiddenField</code>. This field will be present in <code>validated_data</code> but <em>will not</em> be used in the serializer output representation.</p>
<p><strong>Note:</strong> Using a <code>read_only=True</code> field is excluded from writable fields so it won't use a <code>default=…</code> argument. Look <a href="https://www.django-rest-framework.org/community/3.8-announcement/#altered-the-behaviour-of-read_only-plus-default-on-field">3.8 announcement</a>.</p>
<p><strong>Note:</strong> Using a <code>read_only=True</code> field is excluded from writable fields so it won't use a <code>default=…</code> argument. Look <a href="https://www.django-rest-framework.org/community/3.8-announcement/#altered-the-behavior-of-read_only-plus-default-on-field">3.8 announcement</a>.</p>
<p>REST framework includes a couple of defaults that may be useful in this context.</p>
<h4 id="currentuserdefault"><a class="toclink" href="#currentuserdefault">CurrentUserDefault</a></h4>
<p>A default class that can be used to represent the current user. In order to use this, the 'request' must have been provided as part of the context dictionary when instantiating the serializer.</p>

2
community/3.0-announcement/index.html
View File

@ -974,7 +974,7 @@ def all_high_scores(request):
<p>The <code>MultipleChoiceField</code> class has been added. This field acts like <code>ChoiceField</code>, but returns a set, which may include none, one or many of the valid choices.</p>
<h4 id="changes-to-the-custom-field-api"><a class="toclink" href="#changes-to-the-custom-field-api">Changes to the custom field API.</a></h4>
<p>The <code>from_native(self, value)</code> and <code>to_native(self, data)</code> method names have been replaced with the more obviously named <code>to_internal_value(self, data)</code> and <code>to_representation(self, value)</code>.</p>
<p>The <code>field_from_native()</code> and <code>field_to_native()</code> methods are removed. Previously you could use these methods if you wanted to customise the behavior in a way that did not simply lookup the field value from the object. For example...</p>
<p>The <code>field_from_native()</code> and <code>field_to_native()</code> methods are removed. Previously you could use these methods if you wanted to customize the behavior in a way that did not simply lookup the field value from the object. For example...</p>
<pre><code>def field_to_native(self, obj, field_name):
"""A custom read-only field that returns the class name."""
return obj.__class__.__name__

4
community/3.12-announcement/index.html
View File

@ -534,7 +534,7 @@ in the URL path.</p>
<p>See <a href="https://www.django-rest-framework.org/api-guide/schemas/#grouping-operations-with-tags">the schema documentation</a> for more information.</p>
<h2 id="customizing-the-operation-id"><a class="toclink" href="#customizing-the-operation-id">Customizing the operation ID.</a></h2>
<p>REST framework automatically determines operation IDs to use in OpenAPI
schemas. The latest version provides more control for overriding the behaviour
schemas. The latest version provides more control for overriding the behavior
used to generate the operation IDs.</p>
<p>See <a href="https://www.django-rest-framework.org/api-guide/schemas/#operationid">the schema documentation</a> for more information.</p>
<h2 id="support-for-openapi-components"><a class="toclink" href="#support-for-openapi-components">Support for OpenAPI components.</a></h2>
@ -569,7 +569,7 @@ are now available for overriding...</p>
for details on using custom <code>AutoSchema</code> subclasses.</p>
<h2 id="support-for-jsonfield"><a class="toclink" href="#support-for-jsonfield">Support for JSONField.</a></h2>
<p>Django 3.1 deprecated the existing <code>django.contrib.postgres.fields.JSONField</code>
in favour of a new database-agnositic <code>JSONField</code>.</p>
in favor of a new database-agnositic <code>JSONField</code>.</p>
<p>REST framework 3.12 now supports this new model field, and <code>ModelSerializer</code>
classes will correctly map the model field.</p>
<h2 id="searchfilter-improvements"><a class="toclink" href="#searchfilter-improvements">SearchFilter improvements</a></h2>

2
community/3.13-announcement/index.html
View File

@ -484,7 +484,7 @@ are likely in the composite fields, <code>ListField</code> and <code>DictField</
<p>They must now use the more explicit keyword argument style...</p>
<pre><code class="language-python">aliases = serializers.ListField(child=serializers.CharField())
</code></pre>
<p>This change has been made because using positional arguments here <em>does not</em> result in the expected behaviour.</p>
<p>This change has been made because using positional arguments here <em>does not</em> result in the expected behavior.</p>
<p>See Pull Request <a href="https://github.com/encode/django-rest-framework/pull/7632">#7632</a> for more details.</p>

6
community/3.15-announcement/index.html
View File

@ -438,7 +438,7 @@
</li>
<li>
<a href="#align-searchfilter-behaviour-to-djangocontribadmin-search">Align SearchFilter behaviour to django.contrib.admin search</a>
<a href="#align-searchfilter-behavior-to-djangocontribadmin-search">Align SearchFilter behavior to django.contrib.admin search</a>
</li>
<li>
@ -490,10 +490,10 @@
<p>By default the URLs created by <code>SimpleRouter</code> use regular expressions. This behavior can be modified by setting the <code>use_regex_path</code> argument to <code>False</code> when instantiating the router.</p>
<h2 id="zoneinfo-as-the-primary-source-of-timezone-data"><a class="toclink" href="#zoneinfo-as-the-primary-source-of-timezone-data">ZoneInfo as the primary source of timezone data</a></h2>
<p>Dependency on pytz has been removed and deprecation warnings have been added, Django will provide ZoneInfo instances as long as USE_DEPRECATED_PYTZ is not enabled. More info on the migration can be found <a href="https://pytz-deprecation-shim.readthedocs.io/en/latest/migration.html">in this guide</a>.</p>
<h2 id="align-searchfilter-behaviour-to-djangocontribadmin-search"><a class="toclink" href="#align-searchfilter-behaviour-to-djangocontribadmin-search">Align <code>SearchFilter</code> behaviour to <code>django.contrib.admin</code> search</a></h2>
<h2 id="align-searchfilter-behavior-to-djangocontribadmin-search"><a class="toclink" href="#align-searchfilter-behavior-to-djangocontribadmin-search">Align <code>SearchFilter</code> behavior to <code>django.contrib.admin</code> search</a></h2>
<p>Searches now may contain <em>quoted phrases</em> with spaces, each phrase is considered as a single search term, and it will raise a validation error if any null-character is provided in search. See the <a href="../../api-guide/filtering/">Filtering API guide</a> for more information.</p>
<h2 id="other-fixes-and-improvements"><a class="toclink" href="#other-fixes-and-improvements">Other fixes and improvements</a></h2>
<p>There are a number of fixes and minor improvements in this release, ranging from documentation, internal infrastructure (typing, testing, requirements, deprecation, etc.), security and overall behaviour.</p>
<p>There are a number of fixes and minor improvements in this release, ranging from documentation, internal infrastructure (typing, testing, requirements, deprecation, etc.), security and overall behavior.</p>
<p>See the <a href="../release-notes/">release notes</a> page for a complete listing.</p>

4
community/3.16-announcement/index.html
View File

@ -477,11 +477,11 @@
<p>The latest release now fully supports Django 5.1 and the upcoming 5.2 LTS as well as Python 3.13.</p>
<p>The current minimum versions of Django is now 4.2 and Python 3.9.</p>
<h2 id="django-loginrequiredmiddleware"><a class="toclink" href="#django-loginrequiredmiddleware">Django LoginRequiredMiddleware</a></h2>
<p>The new <code>LoginRequiredMiddleware</code> introduced by Django 5.1 can now be used alongside Django REST Framework, however it is not honored for API views as an equivalent behaviour can be configured via <code>DEFAULT_AUTHENTICATION_CLASSES</code>. See <a href="../../api-guide/authentication/#django-51-loginrequiredmiddleware">our dedicated section</a> in the docs for more information.</p>
<p>The new <code>LoginRequiredMiddleware</code> introduced by Django 5.1 can now be used alongside Django REST Framework, however it is not honored for API views as an equivalent behavior can be configured via <code>DEFAULT_AUTHENTICATION_CLASSES</code>. See <a href="../../api-guide/authentication/#django-51-loginrequiredmiddleware">our dedicated section</a> in the docs for more information.</p>
<h2 id="improved-support-for-uniqueconstraint"><a class="toclink" href="#improved-support-for-uniqueconstraint">Improved support for UniqueConstraint</a></h2>
<p>The generation of validators for <a href="https://docs.djangoproject.com/en/stable/ref/models/constraints/#uniqueconstraint">UniqueConstraint</a> has been improved to support better nullable fields and constraints with conditions.</p>
<h2 id="other-fixes-and-improvements"><a class="toclink" href="#other-fixes-and-improvements">Other fixes and improvements</a></h2>
<p>There are a number of fixes and minor improvements in this release, ranging from documentation, internal infrastructure (typing, testing, requirements, deprecation, etc.), security and overall behaviour.</p>
<p>There are a number of fixes and minor improvements in this release, ranging from documentation, internal infrastructure (typing, testing, requirements, deprecation, etc.), security and overall behavior.</p>
<p>See the <a href="../release-notes/">release notes</a> page for a complete listing.</p>

2
community/3.4-announcement/index.html
View File

@ -600,7 +600,7 @@ attribute on a <code>JSONRenderer</code> subclass.</p>
will result in a list of the available choices being returned in the response.</p>
<p>In cases where there is a relational field, the previous behavior would be
to return a list of available instances to choose from for that relational field.</p>
<p>In order to minimise exposed information the behavior now is to <em>not</em> return
<p>In order to minimize exposed information the behavior now is to <em>not</em> return
choices information for relational fields.</p>
<p>If you want to override this new behavior you'll need to <a href="../../api-guide/metadata/#custom-metadata-classes">implement a custom
metadata class</a>.</p>

16
community/3.5-announcement/index.html
View File

@ -545,7 +545,7 @@ so if you're already using schema generation you should make sure to review
a dynamic client library to interact with your API.</p>
<p>Finally, we're also now exposing the schema generation as a
<a href="../../api-guide/schemas/#schemagenerator">publicly documented API</a>, allowing you to more easily
override the behaviour.</p>
override the behavior.</p>
<h2 id="requests-test-client"><a class="toclink" href="#requests-test-client">Requests test client</a></h2>
<p>You can now test your project using the <code>requests</code> library.</p>
<p>This exposes exactly the same interface as if you were using a standard
@ -563,12 +563,12 @@ client library.</p>
client = CoreAPIClient()
schema = client.get('http://testserver/schema/')
# Create a new organisation
# Create a new organization
params = {'name': 'MegaCorp', 'status': 'active'}
client.action(schema, ['organisations', 'create'], params)
client.action(schema, ['organizations', 'create'], params)
# Ensure that the organisation exists in the listing
data = client.action(schema, ['organisations', 'list'])
# Ensure that the organization exists in the listing
data = client.action(schema, ['organizations', 'list'])
assert(len(data) == 1)
assert(data == [{'name': 'MegaCorp', 'status': 'active'}])
</code></pre>
@ -636,14 +636,14 @@ urlpatterns = [
<p>The <code>'pk'</code> identifier in schema paths is now mapped onto the actually model field
name by default. This will typically be <code>'id'</code>.</p>
<p>This gives a better external representation for schemas, with less implementation
detail being exposed. It also reflects the behaviour of using a ModelSerializer
detail being exposed. It also reflects the behavior of using a ModelSerializer
class with <code>fields = '__all__'</code>.</p>
<p>You can revert to the previous behaviour by setting <code>'SCHEMA_COERCE_PATH_PK': False</code>
<p>You can revert to the previous behavior by setting <code>'SCHEMA_COERCE_PATH_PK': False</code>
in the REST framework settings.</p>
<h3 id="schema-action-name-representations"><a class="toclink" href="#schema-action-name-representations">Schema action name representations</a></h3>
<p>The internal <code>retrieve()</code> and <code>destroy()</code> method names are now coerced to an
external representation of <code>read</code> and <code>delete</code>.</p>
<p>You can revert to the previous behaviour by setting <code>'SCHEMA_COERCE_METHOD_NAMES': {}</code>
<p>You can revert to the previous behavior by setting <code>'SCHEMA_COERCE_METHOD_NAMES': {}</code>
in the REST framework settings.</p>
<h3 id="djangofilterbackend"><a class="toclink" href="#djangofilterbackend">DjangoFilterBackend</a></h3>
<p>The functionality of the built-in <code>DjangoFilterBackend</code> is now completely

2
community/3.7-announcement/index.html
View File

@ -502,7 +502,7 @@
<p>The schema generation introduced in 3.5 and the related API docs generation in 3.6 are both hugely powerful features, however they've been somewhat limited in cases where the view introspection isn't able to correctly identify the schema for a particular view.</p>
<p>In order to try to address this we're now adding the ability for per-view customization of the API schema. The interface that we're adding for this allows either basic manual overrides over which fields should be included on a view, or for more complex programmatic overriding of the schema generation. We believe this release comprehensively addresses some of the existing shortcomings of the schema features.</p>
<p>Let's take a quick look at using the new functionality...</p>
<p>The <code>APIView</code> class has a <code>schema</code> attribute, that is used to control how the Schema for that particular view is generated. The default behaviour is to use the <code>AutoSchema</code> class.</p>
<p>The <code>APIView</code> class has a <code>schema</code> attribute, that is used to control how the Schema for that particular view is generated. The default behavior is to use the <code>AutoSchema</code> class.</p>
<pre><code>from rest_framework.views import APIView
from rest_framework.schemas import AutoSchema

4
community/3.8-announcement/index.html
View File

@ -485,12 +485,12 @@ the foundations for future changes.</p>
<p><em>We'd like to say thanks in particular our premium backers, <a href="https://www.rover.com/careers/">Rover</a>, <a href="https://sentry.io/welcome/">Sentry</a>, <a href="https://getstream.io/?utm_source=drf&amp;utm_medium=banner&amp;utm_campaign=drf">Stream</a>, <a href="https://machinalis.com/">Machinalis</a>, and <a href="https://rollbar.com">Rollbar</a>.</em></p>
<hr />
<h2 id="breaking-changes"><a class="toclink" href="#breaking-changes">Breaking Changes</a></h2>
<h3 id="altered-the-behaviour-of-read_only-plus-default-on-field"><a class="toclink" href="#altered-the-behaviour-of-read_only-plus-default-on-field">Altered the behaviour of <code>read_only</code> plus <code>default</code> on Field.</a></h3>
<h3 id="altered-the-behavior-of-read_only-plus-default-on-field"><a class="toclink" href="#altered-the-behavior-of-read_only-plus-default-on-field">Altered the behavior of <code>read_only</code> plus <code>default</code> on Field.</a></h3>
<p><a href="https://github.com/encode/django-rest-framework/issues/5886">#5886</a> <code>read_only</code> fields will now <strong>always</strong> be excluded from writable fields.</p>
<p>Previously <code>read_only</code> fields when combined with a <code>default</code> value would use the <code>default</code> for create and update
operations. This was counter-intuitive in some circumstances and led to difficulties supporting dotted <code>source</code>
attributes on nullable relations.</p>
<p>In order to maintain the old behaviour you may need to pass the value of <code>read_only</code> fields when calling <code>save()</code> in
<p>In order to maintain the old behavior you may need to pass the value of <code>read_only</code> fields when calling <code>save()</code> in
the view:</p>
<pre><code>def perform_create(self, serializer):
serializer.save(owner=self.request.user)

2
community/3.9-announcement/index.html
View File

@ -575,7 +575,7 @@ package. Please use this instead.</p>
<p>See <a href="https://github.com/encode/django-rest-framework/pull/5990">#5990</a>.</p>
<p><code>base_name</code> and <code>get_default_base_name()</code> are pending deprecation. They will be deprecated in 3.10 and removed entirely in 3.11.</p>
<h3 id="action-decorator-replaces-list_route-and-detail_route"><a class="toclink" href="#action-decorator-replaces-list_route-and-detail_route"><code>action</code> decorator replaces <code>list_route</code> and <code>detail_route</code></a></h3>
<p>Both <code>list_route</code> and <code>detail_route</code> are now deprecated in favour of the single <code>action</code> decorator.
<p>Both <code>list_route</code> and <code>detail_route</code> are now deprecated in favor of the single <code>action</code> decorator.
They will be removed entirely in 3.10.</p>
<p>The <code>action</code> decorator takes a boolean <code>detail</code> argument.</p>
<ul>

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

@ -615,7 +615,7 @@
<p><strong>Full Changelog</strong>: https://github.com/encode/django-rest-framework/compare/3.16.0...3.16.1</p>
<h3 id="3160"><a class="toclink" href="#3160">3.16.0</a></h3>
<p><strong>Date</strong>: 28th March 2025</p>
<p>This release is considered a significant release to improve upstream support with Django and Python. Some of these may change the behaviour of existing features and pre-existing behaviour. Specifically, some fixes were added to around the support of <code>UniqueConstraint</code> with nullable fields which will improve built-in serializer validation.</p>
<p>This release is considered a significant release to improve upstream support with Django and Python. Some of these may change the behavior of existing features and pre-existing behavior. Specifically, some fixes were added to around the support of <code>UniqueConstraint</code> with nullable fields which will improve built-in serializer validation.</p>
<h4 id="features"><a class="toclink" href="#features">Features</a></h4>
<ul>
<li>Add official support for Django 5.1 and its new <code>LoginRequiredMiddleware</code> in <a href="https://github.com/encode/django-rest-framework/pull/9514">#9514</a> and <a href="https://github.com/encode/django-rest-framework/pull/9657">#9657</a></li>
@ -719,7 +719,7 @@
<li>Partial serializer should not have required fields [<a href="https://github.com/encode/django-rest-framework/pull/7563">#7563</a>]</li>
<li>Propagate 'default' from model field to serializer field. [<a href="https://github.com/encode/django-rest-framework/pull/9030">#9030</a>]</li>
<li>Allow to override child.run_validation call in ListSerializer [<a href="https://github.com/encode/django-rest-framework/pull/8035">#8035</a>]</li>
<li>Align SearchFilter behaviour to django.contrib.admin search [<a href="https://github.com/encode/django-rest-framework/pull/9017">#9017</a>]</li>
<li>Align SearchFilter behavior to django.contrib.admin search [<a href="https://github.com/encode/django-rest-framework/pull/9017">#9017</a>]</li>
<li>Class name added to unknown field error [<a href="https://github.com/encode/django-rest-framework/pull/9019">#9019</a>]</li>
<li>Fix: Pagination response schemas. [<a href="https://github.com/encode/django-rest-framework/pull/9049">#9049</a>]</li>
<li>Fix choices in ChoiceField to support IntEnum [<a href="https://github.com/encode/django-rest-framework/pull/8955">#8955</a>]</li>
@ -861,7 +861,7 @@
<ul>
<li>Add <code>--file</code> option to <code>generateschema</code> command. [#7130]</li>
<li>Support <code>tags</code> for OpenAPI schema generation. See <a href="https://www.django-rest-framework.org/api-guide/schemas/#grouping-operations-with-tags">the schema docs</a>. [#7184]</li>
<li>Support customising the operation ID for schema generation. See <a href="https://www.django-rest-framework.org/api-guide/schemas/#operationid">the schema docs</a>. [#7190]</li>
<li>Support customizing the operation ID for schema generation. See <a href="https://www.django-rest-framework.org/api-guide/schemas/#operationid">the schema docs</a>. [#7190]</li>
<li>Support OpenAPI components for schema generation. See <a href="https://www.django-rest-framework.org/api-guide/schemas/#components">the schema docs</a>. [#7124]</li>
<li>The following methods on <code>AutoSchema</code> become public API: <code>get_path_parameters</code>, <code>get_pagination_parameters</code>, <code>get_filter_parameters</code>, <code>get_request_body</code>, <code>get_responses</code>, <code>get_serializer</code>, <code>get_paginator</code>, <code>map_serializer</code>, <code>map_field</code>, <code>map_choice_field</code>, <code>map_field_validators</code>, <code>allows_filters</code>. See <a href="https://www.django-rest-framework.org/api-guide/schemas/#autoschema">the schema docs</a></li>
<li>Add support for Django 3.1's database-agnositic <code>JSONField</code>. [#7467]</li>
@ -899,14 +899,14 @@
<li>Fix <code>PrimaryKeyRelatedField</code> and <code>HyperlinkedRelatedField</code> when source field is actually a property. [#7142]</li>
<li><code>Token.generate_key</code> is now a class method. [#7502]</li>
<li><code>@action</code> warns if method is wrapped in a decorator that does not preserve information using <code>@functools.wraps</code>. [#7098]</li>
<li>Deprecate <code>serializers.NullBooleanField</code> in favour of <code>serializers.BooleanField</code> with <code>allow_null=True</code> [#7122]</li>
<li>Deprecate <code>serializers.NullBooleanField</code> in favor of <code>serializers.BooleanField</code> with <code>allow_null=True</code> [#7122]</li>
</ul>
<hr />
<h2 id="311x-series"><a class="toclink" href="#311x-series">3.11.x series</a></h2>
<h3 id="3112"><a class="toclink" href="#3112">3.11.2</a></h3>
<p><strong>Date</strong>: 30th September 2020</p>
<ul>
<li><strong>Security</strong>: Drop <code>urlize_quoted_links</code> template tag in favour of Django's built-in <code>urlize</code>. Removes a XSS vulnerability for some kinds of content in the browsable API.</li>
<li><strong>Security</strong>: Drop <code>urlize_quoted_links</code> template tag in favor of Django's built-in <code>urlize</code>. Removes a XSS vulnerability for some kinds of content in the browsable API.</li>
</ul>
<h3 id="3111"><a class="toclink" href="#3111">3.11.1</a></h3>
<p><strong>Date</strong>: 5th August 2020</p>
@ -916,7 +916,7 @@
<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>Drop <code>.set_context</code> API <a href="../3.11-announcement/#validator-default-context">in favor 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>
@ -1087,10 +1087,10 @@ basing it on the <code>url_path</code> instead of the function name.</p>
<p><strong>Date</strong>: <a href="https://github.com/encode/django-rest-framework/milestone/61?closed=1">3rd April 2018</a></p>
<ul>
<li>
<p><strong>Breaking Change</strong>: Alter <code>read_only</code> plus <code>default</code> behaviour. <a href="https://github.com/encode/django-rest-framework/issues/5886">#5886</a></p>
<p><strong>Breaking Change</strong>: Alter <code>read_only</code> plus <code>default</code> behavior. <a href="https://github.com/encode/django-rest-framework/issues/5886">#5886</a></p>
<p><code>read_only</code> fields will now <strong>always</strong> be excluded from writable fields.</p>
<p>Previously <code>read_only</code> fields with a <code>default</code> value would use the <code>default</code> for create and update operations.</p>
<p>In order to maintain the old behaviour you may need to pass the value of <code>read_only</code> fields when calling <code>save()</code> in
<p>In order to maintain the old behavior you may need to pass the value of <code>read_only</code> fields when calling <code>save()</code> in
the view:</p>
<pre><code>def perform_create(self, serializer):
serializer.save(owner=self.request.user)
@ -1098,11 +1098,11 @@ the view:</p>
<p>Alternatively you may override <code>save()</code> or <code>create()</code> or <code>update()</code> on the serializer as appropriate.</p>
</li>
<li>
<p>Correct allow_null behaviour when required=False <a href="https://github.com/encode/django-rest-framework/issues/5888">#5888</a></p>
<p>Correct allow_null behavior when required=False <a href="https://github.com/encode/django-rest-framework/issues/5888">#5888</a></p>
<p>Without an explicit <code>default</code>, <code>allow_null</code> implies a default of <code>null</code> for outgoing serialization. Previously such
fields were being skipped when read-only or otherwise not required.</p>
<p><strong>Possible backwards compatibility break</strong> if you were relying on such fields being excluded from the outgoing
representation. In order to restore the old behaviour you can override <code>data</code> to exclude the field when <code>None</code>.</p>
representation. In order to restore the old behavior you can override <code>data</code> to exclude the field when <code>None</code>.</p>
<p>For example:</p>
<pre><code>@property
def data(self):
@ -1161,7 +1161,7 @@ it to introspect its set of actions and the details of the current action.</p>
<li>Add HStoreField, postgres fields tests <a href="https://github.com/encode/django-rest-framework/issues/5654">#5654</a></li>
<li>Always fully qualify ValidationError in docs <a href="https://github.com/encode/django-rest-framework/issues/5751">#5751</a></li>
<li>Remove unreachable code from ManualSchema <a href="https://github.com/encode/django-rest-framework/issues/5766">#5766</a></li>
<li>Allowed customising API documentation code samples <a href="https://github.com/encode/django-rest-framework/issues/5752">#5752</a></li>
<li>Allowed customizing API documentation code samples <a href="https://github.com/encode/django-rest-framework/issues/5752">#5752</a></li>
<li>Updated docs to use <code>pip show</code> <a href="https://github.com/encode/django-rest-framework/issues/5757">#5757</a></li>
<li>Load 'static' instead of 'staticfiles' in templates <a href="https://github.com/encode/django-rest-framework/issues/5773">#5773</a></li>
<li>Fixed a typo in <code>fields</code> docs <a href="https://github.com/encode/django-rest-framework/issues/5783">#5783</a></li>
@ -1218,7 +1218,7 @@ it to introspect its set of actions and the details of the current action.</p>
<ul>
<li>
<p>Schema: Extract method for <code>manual_fields</code> processing <a href="https://github.com/encode/django-rest-framework/issues/5633">#5633</a></p>
<p>Allows for easier customisation of <code>manual_fields</code> processing, for example
<p>Allows for easier customization of <code>manual_fields</code> processing, for example
to provide per-method manual fields. <code>AutoSchema</code> adds <code>get_manual_fields</code>,
as the intended override point, and a utility method <code>update_fields</code>, to
handle by-name field replacement from a list, which, in general, you are not
@ -1334,7 +1334,7 @@ Previously may have been stored internally as <code>None</code>.</p>
<li>Don't strip microseconds from <code>time</code> when encoding. Makes consistent with <code>datetime</code>.
<strong>BC Change</strong>: Previously only milliseconds were encoded. <a href="https://github.com/encode/django-rest-framework/issues/5440">#5440</a></li>
<li>Added <code>STRICT_JSON</code> setting (default <code>True</code>) to raise exception for the extended float values (<code>nan</code>, <code>inf</code>, <code>-inf</code>) accepted by Python's <code>json</code> module.
<strong>BC Change</strong>: Previously these values would converted to corresponding strings. Set <code>STRICT_JSON</code> to <code>False</code> to restore the previous behaviour. <a href="https://github.com/encode/django-rest-framework/issues/5265">#5265</a></li>
<strong>BC Change</strong>: Previously these values would converted to corresponding strings. Set <code>STRICT_JSON</code> to <code>False</code> to restore the previous behavior. <a href="https://github.com/encode/django-rest-framework/issues/5265">#5265</a></li>
<li>Add support for <code>page_size</code> parameter in CursorPaginator class <a href="https://github.com/encode/django-rest-framework/issues/5250">#5250</a></li>
<li>Make <code>DEFAULT_PAGINATION_CLASS</code> <code>None</code> by default.
<strong>BC Change</strong>: If your were <strong>just</strong> setting <code>PAGE_SIZE</code> to enable pagination you will need to add <code>DEFAULT_PAGINATION_CLASS</code>.
@ -1372,10 +1372,10 @@ Previously may have been stored internally as <code>None</code>.</p>
<li>Fix naming collisions in Schema Generation <a href="https://github.com/encode/django-rest-framework/issues/5464">#5464</a></li>
<li>Call Django's authenticate function with the request object <a href="https://github.com/encode/django-rest-framework/issues/5295">#5295</a></li>
<li>Update coreapi JS to 0.1.1 <a href="https://github.com/encode/django-rest-framework/issues/5479">#5479</a></li>
<li>Have <code>is_list_view</code> recognise RetrieveModel… views <a href="https://github.com/encode/django-rest-framework/issues/5480">#5480</a></li>
<li>Have <code>is_list_view</code> recognize RetrieveModel… views <a href="https://github.com/encode/django-rest-framework/issues/5480">#5480</a></li>
<li>Remove Django 1.8 &amp; 1.9 compatibility code <a href="https://github.com/encode/django-rest-framework/issues/5481">#5481</a></li>
<li>Remove deprecated schema code from DefaultRouter <a href="https://github.com/encode/django-rest-framework/issues/5482">#5482</a></li>
<li>Refactor schema generation to allow per-view customisation.
<li>Refactor schema generation to allow per-view customization.
<strong>BC Change</strong>: <code>SchemaGenerator.get_serializer_fields</code> has been refactored as <code>AutoSchema.get_serializer_fields</code> and drops the <code>view</code> argument [#5354][gh5354]</li>
</ul>
<h2 id="36x-series"><a class="toclink" href="#36x-series">3.6.x series</a></h2>

2
index.html
View File

@ -541,7 +541,7 @@
<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>Extensive documentation, 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="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>
<li>Used and trusted by internationally recognized 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>

2
search/search_index.json
View File

File diff suppressed because one or more lines are too long

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

@ -577,7 +577,7 @@ urlpatterns = [
<li><code>FORMAT_PARAM</code> : The view can accept a format override</li>
<li><code>METHOD_PARAM</code> : The view can accept a method override</li>
</ul>
<p>You can override the <code>BrowsableAPIRenderer.get_context()</code> method to customise the context that gets passed to the template.</p>
<p>You can override the <code>BrowsableAPIRenderer.get_context()</code> method to customize the context that gets passed to the template.</p>
<h4 id="not-using-basehtml"><a class="toclink" href="#not-using-basehtml">Not using base.html</a></h4>
<p>For more advanced customization, such as not having a Bootstrap basis or tighter integration with the rest of your site, you can simply choose not to have <code>api.html</code> extend <code>base.html</code>. Then the page content and capabilities are entirely up to you.</p>
<h4 id="handling-choicefield-with-large-numbers-of-items"><a class="toclink" href="#handling-choicefield-with-large-numbers-of-items">Handling <code>ChoiceField</code> with large numbers of items.</a></h4>

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

@ -472,7 +472,7 @@ the Design of Network-based Software Architectures</a>.</li>
<p>It is self evident that REST framework makes it possible to build Hypermedia APIs. The browsable API that it offers is built on HTML - the hypermedia language of the web.</p>
<p>REST framework also includes <a href="../../api-guide/serializers/">serialization</a> and <a href="../../api-guide/parsers/">parser</a>/<a href="../../api-guide/renderers/">renderer</a> components that make it easy to build appropriate media types, <a href="../../api-guide/fields/">hyperlinked relations</a> for building well-connected systems, and great support for <a href="../../api-guide/content-negotiation/">content negotiation</a>.</p>
<h2 id="what-rest-framework-doesnt-provide"><a class="toclink" href="#what-rest-framework-doesnt-provide">What REST framework doesn't provide.</a></h2>
<p>What REST framework doesn't do is give you machine readable hypermedia formats such as <a href="http://stateless.co/hal_specification.html">HAL</a>, <a href="http://www.amundsen.com/media-types/collection/">Collection+JSON</a>, <a href="http://jsonapi.org/">JSON API</a> or HTML <a href="http://microformats.org/wiki/Main_Page">microformats</a> by default, or the ability to auto-magically create fully HATEOAS style APIs that include hypermedia-based form descriptions and semantically labelled hyperlinks. Doing so would involve making opinionated choices about API design that should really remain outside of the framework's scope.</p>
<p>What REST framework doesn't do is give you machine readable hypermedia formats such as <a href="http://stateless.co/hal_specification.html">HAL</a>, <a href="http://www.amundsen.com/media-types/collection/">Collection+JSON</a>, <a href="http://jsonapi.org/">JSON API</a> or HTML <a href="http://microformats.org/wiki/Main_Page">microformats</a> by default, or the ability to auto-magically create fully HATEOAS style APIs that include hypermedia-based form descriptions and semantically labeled hyperlinks. Doing so would involve making opinionated choices about API design that should really remain outside of the framework's scope.</p>
</div> <!--/span-->