You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
<p>HTTP 401 responses must always include a <code>WWW-Authenticate</code> header, that instructs the client how to authenticate. HTTP 403 responses do not include the <code>WWW-Authenticate</code> header.</p>
606
610
<p>The kind of response that will be used depends on the authentication scheme. Although multiple authentication schemes may be in use, only one scheme may be used to determine the type of response. <strong>The first authentication class set on the view is used when determining the type of response</strong>.</p>
607
611
<p>Note that when a request may successfully authenticate, but still be denied permission to perform the request, in which case a <code>403 Permission Denied</code> response will always be used, regardless of the authentication scheme.</p>
<p>If you're running Django 5.1+ and use the <ahref="https://docs.djangoproject.com/en/stable/ref/middleware/#django.contrib.auth.middleware.LoginRequiredMiddleware"><code>LoginRequiredMiddleware</code></a>, please note that all views from DRF are opted-out of this middleware. This is because the authentication in DRF is based authentication and permissions classes, which may be determined after the middleware has been applied. Additionally, when the request is not authenticated, the middleware redirects the user to the login page, which is not suitable for API requests, where it's preferable to return a 401 status code.</p>
614
+
<p>REST framework offers an equivalent mechanism for DRF views via the global settings, <code>DEFAULT_AUTHENTICATION_CLASSES</code> and <code>DEFAULT_PERMISSION_CLASSES</code>. They should be changed accordingly if you need to enforce that API requests are logged in.</p>
608
615
<h2id="apache-mod_wsgi-specific-configuration"><aclass="toclink" href="#apache-mod_wsgi-specific-configuration">Apache mod_wsgi specific configuration</a></h2>
609
616
<p>Note that if deploying to <ahref="https://modwsgi.readthedocs.io/en/develop/configuration-directives/WSGIPassAuthorization.html">Apache using mod_wsgi</a>, the authorization header is not passed through to a WSGI application by default, as it is assumed that authentication will be handled by Apache, rather than at an application level.</p>
610
617
<p>If you are deploying to Apache, and using any non-session based authentication, you will need to explicitly configure mod_wsgi to pass the required headers through to the application. This can be done by specifying the <code>WSGIPassAuthorization</code> directive in the appropriate context and setting it to <code>'On'</code>.</p>
<li><code>max_digits</code> The maximum number of digits allowed in the number. It must be either <code>None</code> or an integer greater than or equal to <code>decimal_places</code>.</li>
833
833
<li><code>decimal_places</code> The number of decimal places to store with the number.</li>
834
834
<li><code>coerce_to_string</code> Set to <code>True</code> if string values should be returned for the representation, or <code>False</code> if <code>Decimal</code> objects should be returned. Defaults to the same value as the <code>COERCE_DECIMAL_TO_STRING</code> settings key, which will be <code>True</code> unless overridden. If <code>Decimal</code> objects are returned by the serializer, then the final output format will be determined by the renderer. Note that setting <code>localize</code> will force the value to <code>True</code>.</li>
835
-
<li><code>max_value</code> Validate that the number provided is no greater than this value.</li>
836
-
<li><code>min_value</code> Validate that the number provided is no less than this value.</li>
835
+
<li><code>max_value</code> Validate that the number provided is no greater than this value. Should be an integer or <code>Decimal</code> object.</li>
836
+
<li><code>min_value</code> Validate that the number provided is no less than this value. Should be an integer or <code>Decimal</code> object.</li>
837
837
<li><code>localize</code> Set to <code>True</code> to enable localization of input and output based on the current locale. This will also force <code>coerce_to_string</code> to <code>True</code>. Defaults to <code>False</code>. Note that data formatting is enabled if you have set <code>USE_L10N=True</code> in your settings file.</li>
838
838
<li><code>rounding</code> Sets the rounding mode used when quantizing to the configured precision. Valid values are <ahref="https://docs.python.org/3/library/decimal.html#rounding-modes"><code>decimal</code> module rounding modes</a>. Defaults to <code>None</code>.</li>
839
839
<li><code>normalize_output</code> Will normalize the decimal value when serialized. This will strip all trailing zeroes and change the value's precision to the minimum required precision to be able to represent the value without losing data. Defaults to <code>False</code>.</li>
<p><ahref="https://github.com/wq/django-rest-pandas">Django REST Pandas</a> provides a serializer and renderers that support additional data processing and output via the <ahref="https://pandas.pydata.org/">Pandas</a> DataFrame API. Django REST Pandas includes renderers for Pandas-style CSV files, Excel workbooks (both <code>.xls</code> and <code>.xlsx</code>), and a number of <ahref="https://github.com/wq/django-rest-pandas#supported-formats">other formats</a>. It is maintained by <ahref="https://github.com/sheppard">S. Andrew Sheppard</a> as part of the <ahref="https://github.com/wq">wq Project</a>.</p>
<p><ahref="https://github.com/mypebble/rest-framework-latex">Rest Framework Latex</a> provides a renderer that outputs PDFs using Laulatex. It is maintained by <ahref="https://github.com/mypebble">Pebble (S/F Software)</a>.</p>
945
+
<p><ahref="https://github.com/mypebble/rest-framework-latex">Rest Framework Latex</a> provides a renderer that outputs PDFs using Lualatex. It is maintained by <ahref="https://github.com/mypebble">Pebble (S/F Software)</a>.</p>
<h3id="using-django-path-with-routers"><aclass="toclink" href="#using-django-path-with-routers">Using Django <code>path()</code> with routers</a></h3>
610
+
<p>By default, the URLs created by routers 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, in this case <ahref="https://docs.djangoproject.com/en/2.0/topics/http/urls/#path-converters">path converters</a> are used. For example:</p>
<p>The router will match lookup values containing any characters except slashes and period characters. For a more restrictive (or lenient) lookup pattern, set the <code>lookup_value_regex</code> attribute on the viewset or <code>lookup_value_converter</code> if using path converters. For example, you can limit the lookup to valid UUIDs:</p>
<p>This router includes routes for the standard set of <code>list</code>, <code>create</code>, <code>retrieve</code>, <code>update</code>, <code>partial_update</code> and <code>destroy</code> actions. The viewset can also mark additional methods to be routed, using the <code>@action</code> decorator.</p>
<tr><td>{prefix}/{lookup}/{url_path}/</td><td>GET, or as specified by `methods` argument</td><td>`@action(detail=True)` decorated method</td><td>{basename}-{url_name}</td></tr>
622
636
</table>
623
637
624
-
<p>By default the URLs created by <code>SimpleRouter</code> are appended with a trailing slash.
638
+
<p>By default, the URLs created by <code>SimpleRouter</code> are appended with a trailing slash.
625
639
This behavior can be modified by setting the <code>trailing_slash</code> argument to <code>False</code> when instantiating the router. For example:</p>
<p>Trailing slashes are conventional in Django, but are not used by default in some other frameworks such as Rails. Which style you choose to use is largely a matter of preference, although some javascript frameworks may expect a particular routing style.</p>
629
-
<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, in this case <ahref="https://docs.djangoproject.com/en/2.0/topics/http/urls/#path-converters">path converters</a> are used. For example:</p>
<p><strong>Note</strong>: <code>use_regex_path=False</code> only works with Django 2.x or above, since this feature was introduced in 2.0.0. See <ahref="https://docs.djangoproject.com/en/2.0/releases/2.0/#simplified-url-routing-syntax">release note</a></p>
633
-
<p>The router will match lookup values containing any characters except slashes and period characters. For a more restrictive (or lenient) lookup pattern, set the <code>lookup_value_regex</code> attribute on the viewset or <code>lookup_value_converter</code> if using path converters. For example, you can limit the lookup to valid UUIDs:</p>
<p>This router is similar to <code>SimpleRouter</code> as above, but additionally includes a default API root view, that returns a response containing hyperlinks to all the list views. It also generates routes for optional <code>.json</code> style format suffixes.</p>
<p>Serializer classes can also include reusable validators that are applied to the complete set of field data. These validators are included by declaring them on an inner <code>Meta</code> class, like so:</p>
<p>A format string that should be used by default for rendering the output of <code>DateTimeField</code> serializer fields. If <code>None</code>, then <code>DateTimeField</code> serializer fields will return Python <code>datetime</code> objects, and the datetime encoding will be determined by the renderer.</p>
660
-
<p>May be any of <code>None</code>, <code>'iso-8601'</code> or a Python <ahref="https://docs.python.org/3/library/time.html#time.strftime">strftime format</a> string.</p>
660
+
<p>May be any of <code>None</code>, <code>'iso-8601'</code> or a Python <ahref="https://docs.python.org/3/library/datetime.html#strftime-and-strptime-format-codes">strftime format</a> string.</p>
<p>A list of format strings that should be used by default for parsing inputs to <code>DateTimeField</code> serializer fields.</p>
664
-
<p>May be a list including the string <code>'iso-8601'</code> or Python <ahref="https://docs.python.org/3/library/time.html#time.strftime">strftime format</a> strings.</p>
664
+
<p>May be a list including the string <code>'iso-8601'</code> or Python <ahref="https://docs.python.org/3/library/datetime.html#strftime-and-strptime-format-codes">strftime format</a> strings.</p>
<p>A format string that should be used by default for rendering the output of <code>DateField</code> serializer fields. If <code>None</code>, then <code>DateField</code> serializer fields will return Python <code>date</code> objects, and the date encoding will be determined by the renderer.</p>
668
-
<p>May be any of <code>None</code>, <code>'iso-8601'</code> or a Python <ahref="https://docs.python.org/3/library/time.html#time.strftime">strftime format</a> string.</p>
668
+
<p>May be any of <code>None</code>, <code>'iso-8601'</code> or a Python <ahref="https://docs.python.org/3/library/datetime.html#strftime-and-strptime-format-codes">strftime format</a> string.</p>
<p>A list of format strings that should be used by default for parsing inputs to <code>DateField</code> serializer fields.</p>
672
-
<p>May be a list including the string <code>'iso-8601'</code> or Python <ahref="https://docs.python.org/3/library/time.html#time.strftime">strftime format</a> strings.</p>
672
+
<p>May be a list including the string <code>'iso-8601'</code> or Python <ahref="https://docs.python.org/3/library/datetime.html#strftime-and-strptime-format-codes">strftime format</a> strings.</p>
<p>A format string that should be used by default for rendering the output of <code>TimeField</code> serializer fields. If <code>None</code>, then <code>TimeField</code> serializer fields will return Python <code>time</code> objects, and the time encoding will be determined by the renderer.</p>
676
-
<p>May be any of <code>None</code>, <code>'iso-8601'</code> or a Python <ahref="https://docs.python.org/3/library/time.html#time.strftime">strftime format</a> string.</p>
676
+
<p>May be any of <code>None</code>, <code>'iso-8601'</code> or a Python <ahref="https://docs.python.org/3/library/datetime.html#strftime-and-strptime-format-codes">strftime format</a> string.</p>
<p>A list of format strings that should be used by default for parsing inputs to <code>TimeField</code> serializer fields.</p>
680
-
<p>May be a list including the string <code>'iso-8601'</code> or Python <ahref="https://docs.python.org/3/library/time.html#time.strftime">strftime format</a> strings.</p>
680
+
<p>May be a list including the string <code>'iso-8601'</code> or Python <ahref="https://docs.python.org/3/library/datetime.html#strftime-and-strptime-format-codes">strftime format</a> strings.</p>
<h4id="using-the-format-argument"><aclass="toclink" href="#using-the-format-argument">Using the <code>format</code> argument</a></h4>
574
-
<p>Methods which create a request body, such as <code>post</code>, <code>put</code> and <code>patch</code>, include a <code>format</code> argument, which make it easy to generate requests using a content type other than multipart form data. For example:</p>
577
+
<p>Methods which create a request body, such as <code>post</code>, <code>put</code> and <code>patch</code>, include a <code>format</code> argument, which make it easy to generate requests using a wide set of request formats. When using this argument, the factory will select an appropriate renderer and its configured <code>content_type</code>. For example:</p>
<h4id="put-and-patch-with-form-data"><aclass="toclink" href="#put-and-patch-with-form-data">PUT and PATCH with form data</a></h4>
586
589
<p>One difference worth noting between Django's <code>RequestFactory</code> and REST framework's <code>APIRequestFactory</code> is that multipart form data will be encoded for methods other than just <code>.post()</code>.</p>
<p>The interesting bit here is the <code>reference</code> field. We can see that the uniqueness constraint is being explicitly enforced by a validator on the serializer field.</p>
0 commit comments