Skip to content

Commit

Permalink
Deployed 0b2c03b with MkDocs version: 1.1.2
Browse files Browse the repository at this point in the history
  • Loading branch information
@tomchristie
tomchristie committed Nov 29, 2023
1 parent c8d45f9 commit 5796b1a
Show file tree
Hide file tree
Showing 78 changed files with 453 additions and 4,698 deletions.
4 changes: 0 additions & 4 deletions 404.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -238,10 +238,6 @@
<a href="/topics/documenting-your-api/">Documenting your API</a>
</li>

<li >
<a href="/topics/api-clients/">API Clients</a>
</li>

<li >
<a href="/topics/internationalization/">Internationalization</a>
</li>
Expand Down
22 changes: 9 additions & 13 deletions api-guide/authentication/index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -238,10 +238,6 @@
<a href="../../topics/documenting-your-api/">Documenting your API</a>
</li>

<li >
<a href="../../topics/api-clients/">API Clients</a>
</li>

<li >
<a href="../../topics/internationalization/">Internationalization</a>
</li>
Expand Down Expand Up @@ -684,7 +680,7 @@ <h4 id="by-using-signals"><a class="toclink" href="#by-using-signals">By using s
Token.objects.get_or_create(user=user)
</code></pre>
<h4 id="by-exposing-an-api-endpoint"><a class="toclink" href="#by-exposing-an-api-endpoint">By exposing an api endpoint</a></h4>
<p>When using <code>TokenAuthentication</code>, you may want to provide a mechanism for clients to obtain a token given the username and password. REST framework provides a built-in view to provide this behaviour. To use it, add the <code>obtain_auth_token</code> view to your URLconf:</p>
<p>When using <code>TokenAuthentication</code>, you may want to provide a mechanism for clients to obtain a token given the username and password. REST framework provides a built-in view to provide this behavior. To use it, add the <code>obtain_auth_token</code> view to your URLconf:</p>
<pre><code>from rest_framework.authtoken import views
urlpatterns += [
path('api-token-auth/', views.obtain_auth_token)
Expand All @@ -695,7 +691,7 @@ <h4 id="by-exposing-an-api-endpoint"><a class="toclink" href="#by-exposing-an-ap
<pre><code>{ 'token' : '9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b' }
</code></pre>
<p>Note that the default <code>obtain_auth_token</code> view explicitly uses JSON requests and responses, rather than using default renderer and parser classes in your settings.</p>
<p>By default, there are no permissions or throttling applied to the <code>obtain_auth_token</code> view. If you do wish to apply to throttle you'll need to override the view class,
<p>By default, there are no permissions or throttling applied to the <code>obtain_auth_token</code> view. If you do wish to apply throttling you'll need to override the view class,
and include them using the <code>throttle_classes</code> attribute.</p>
<p>If you need a customized version of the <code>obtain_auth_token</code> view, you can do so by subclassing the <code>ObtainAuthToken</code> view class, and using that in your url conf instead.</p>
<p>For example, you may return additional user information beyond the <code>token</code> value:</p>
Expand Down Expand Up @@ -723,7 +719,7 @@ <h4 id="by-exposing-an-api-endpoint"><a class="toclink" href="#by-exposing-an-ap
]
</code></pre>
<h4 id="with-django-admin"><a class="toclink" href="#with-django-admin">With Django admin</a></h4>
<p>It is also possible to create Tokens manually through the admin interface. In case you are using a large user base, we recommend that you monkey patch the <code>TokenAdmin</code> class customize it to your needs, more specifically by declaring the <code>user</code> field as <code>raw_field</code>.</p>
<p>It is also possible to create Tokens manually through the admin interface. In case you are using a large user base, we recommend that you monkey patch the <code>TokenAdmin</code> class to customize it to your needs, more specifically by declaring the <code>user</code> field as <code>raw_field</code>.</p>
<p><code>your_app/admin.py</code>:</p>
<pre><code>from rest_framework.authtoken.admin import TokenAdmin

Expand All @@ -747,22 +743,22 @@ <h2 id="sessionauthentication"><a class="toclink" href="#sessionauthentication">
<li><code>request.auth</code> will be <code>None</code>.</li>
</ul>
<p>Unauthenticated responses that are denied permission will result in an <code>HTTP 403 Forbidden</code> response.</p>
<p>If you're using an AJAX-style API with SessionAuthentication, you'll need to make sure you include a valid CSRF token for any "unsafe" HTTP method calls, such as <code>PUT</code>, <code>PATCH</code>, <code>POST</code> or <code>DELETE</code> requests. See the <a href="https://docs.djangoproject.com/en/stable/ref/csrf/#ajax">Django CSRF documentation</a> for more details.</p>
<p>If you're using an AJAX-style API with SessionAuthentication, you'll need to make sure you include a valid CSRF token for any "unsafe" HTTP method calls, such as <code>PUT</code>, <code>PATCH</code>, <code>POST</code> or <code>DELETE</code> requests. See the <a href="https://docs.djangoproject.com/en/stable/howto/csrf/#using-csrf-protection-with-ajax">Django CSRF documentation</a> for more details.</p>
<p><strong>Warning</strong>: Always use Django's standard login view when creating login pages. This will ensure your login views are properly protected.</p>
<p>CSRF validation in REST framework works slightly differently from standard Django due to the need to support both session and non-session based authentication to the same views. This means that only authenticated requests require CSRF tokens, and anonymous requests may be sent without CSRF tokens. This behaviour is not suitable for login views, which should always have CSRF validation applied.</p>
<p>CSRF validation in REST framework works slightly differently from standard Django due to the need to support both session and non-session based authentication to the same views. This means that only authenticated requests require CSRF tokens, and anonymous requests may be sent without CSRF tokens. This behavior is not suitable for login views, which should always have CSRF validation applied.</p>
<h2 id="remoteuserauthentication"><a class="toclink" href="#remoteuserauthentication">RemoteUserAuthentication</a></h2>
<p>This authentication scheme allows you to delegate authentication to your web server, which sets the <code>REMOTE_USER</code>
environment variable.</p>
<p>To use it, you must have <code>django.contrib.auth.backends.RemoteUserBackend</code> (or a subclass) in your
<code>AUTHENTICATION_BACKENDS</code> setting. By default, <code>RemoteUserBackend</code> creates <code>User</code> objects for usernames that don't
already exist. To change this and other behaviour, consult the
already exist. To change this and other behavior, consult the
<a href="https://docs.djangoproject.com/en/stable/howto/auth-remote-user/">Django documentation</a>.</p>
<p>If successfully authenticated, <code>RemoteUserAuthentication</code> provides the following credentials:</p>
<ul>
<li><code>request.user</code> will be a Django <code>User</code> instance.</li>
<li><code>request.auth</code> will be <code>None</code>.</li>
</ul>
<p>Consult your web server's documentation for information about configuring an authentication method, e.g.:</p>
<p>Consult your web server's documentation for information about configuring an authentication method, for example:</p>
<ul>
<li><a href="https://httpd.apache.org/docs/2.4/howto/auth.html">Apache Authentication How-To</a></li>
<li><a href="https://docs.nginx.com/nginx/admin-guide/security-controls/configuring-http-basic-authentication/">NGINX (Restricting Access)</a></li>
Expand Down Expand Up @@ -836,9 +832,9 @@ <h2 id="json-web-token-authentication"><a class="toclink" href="#json-web-token-
<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>
<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>
<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>
<p><a href="https://github.com/sunscrapers/djoser">Djoser</a> library provides a set of views to handle basic actions such as registration, login, logout, password reset and account activation. The package works with a custom user model and uses token-based authentication. This is ready to use REST implementation of the Django authentication system.</p>
<p><a href="https://github.com/sunscrapers/djoser">Djoser</a> library provides a set of views to handle basic actions such as registration, login, logout, password reset and account activation. The package works with a custom user model and uses token-based authentication. This is a ready to use REST implementation of the Django authentication system.</p>
<h2 id="django-rest-auth-dj-rest-auth"><a class="toclink" href="#django-rest-auth-dj-rest-auth">django-rest-auth / dj-rest-auth</a></h2>
<p>This library provides a set of REST API endpoints for registration, authentication (including social media authentication), password reset, retrieve and update user details, etc. By having these API endpoints, your client apps such as AngularJS, iOS, Android, and others can communicate to your Django backend site independently via REST APIs for user management.</p>
<p>There are currently two forks of this project.</p>
Expand Down
20 changes: 8 additions & 12 deletions api-guide/caching/index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -238,10 +238,6 @@
<a href="../../topics/documenting-your-api/">Documenting your API</a>
</li>

<li >
<a href="../../topics/api-clients/">API Clients</a>
</li>

<li >
<a href="../../topics/internationalization/">Internationalization</a>
</li>
Expand Down Expand Up @@ -461,33 +457,33 @@ <h2 id="using-cache-with-apiview-and-viewsets"><a class="toclink" href="#using-c

class UserViewSet(viewsets.ViewSet):
# With cookie: cache requested url for each user for 2 hours
@method_decorator(cache_page(60*60*2))
@method_decorator(cache_page(60 * 60 * 2))
@method_decorator(vary_on_cookie)
def list(self, request, format=None):
content = {
'user_feed': request.user.get_user_feed()
&quot;user_feed&quot;: request.user.get_user_feed(),
}
return Response(content)


class ProfileView(APIView):
# With auth: cache requested url for each user for 2 hours
@method_decorator(cache_page(60*60*2))
@method_decorator(vary_on_headers(&quot;Authorization&quot;,))
@method_decorator(cache_page(60 * 60 * 2))
@method_decorator(vary_on_headers(&quot;Authorization&quot;))
def get(self, request, format=None):
content = {
'user_feed': request.user.get_user_feed()
&quot;user_feed&quot;: request.user.get_user_feed(),
}
return Response(content)


class PostView(APIView):
# Cache page for the requested url
@method_decorator(cache_page(60*60*2))
@method_decorator(cache_page(60 * 60 * 2))
def get(self, request, format=None):
content = {
'title': 'Post title',
'body': 'Post content'
&quot;title&quot;: &quot;Post title&quot;,
&quot;body&quot;: &quot;Post content&quot;,
}
return Response(content)
</code></pre>
Expand Down
4 changes: 0 additions & 4 deletions api-guide/content-negotiation/index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -238,10 +238,6 @@
<a href="../../topics/documenting-your-api/">Documenting your API</a>
</li>

<li >
<a href="../../topics/api-clients/">API Clients</a>
</li>

<li >
<a href="../../topics/internationalization/">Internationalization</a>
</li>
Expand Down
11 changes: 3 additions & 8 deletions api-guide/exceptions/index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -238,10 +238,6 @@
<a href="../../topics/documenting-your-api/">Documenting your API</a>
</li>

<li >
<a href="../../topics/api-clients/">API Clients</a>
</li>

<li >
<a href="../../topics/internationalization/">Internationalization</a>
</li>
Expand Down Expand Up @@ -595,7 +591,7 @@ <h1 id="api-reference"><a class="toclink" href="#api-reference">API Reference</a
<h2 id="apiexception"><a class="toclink" href="#apiexception">APIException</a></h2>
<p><strong>Signature:</strong> <code>APIException()</code></p>
<p>The <strong>base class</strong> for all exceptions raised inside an <code>APIView</code> class or <code>@api_view</code>.</p>
<p>To provide a custom exception, subclass <code>APIException</code> and set the <code>.status_code</code>, <code>.default_detail</code>, and <code>default_code</code> attributes on the class.</p>
<p>To provide a custom exception, subclass <code>APIException</code> and set the <code>.status_code</code>, <code>.default_detail</code>, and <code>.default_code</code> attributes on the class.</p>
<p>For example, if your API relies on a third party service that may sometimes be unreachable, you might want to implement an exception for the "503 Service Unavailable" HTTP response code. You could do this like so:</p>
<pre><code>from rest_framework.exceptions import APIException

Expand Down Expand Up @@ -649,7 +645,7 @@ <h2 id="permissiondenied"><a class="toclink" href="#permissiondenied">Permission
<p>By default this exception results in a response with the HTTP status code "403 Forbidden".</p>
<h2 id="notfound"><a class="toclink" href="#notfound">NotFound</a></h2>
<p><strong>Signature:</strong> <code>NotFound(detail=None, code=None)</code></p>
<p>Raised when a resource does not exists at the given URL. This exception is equivalent to the standard <code>Http404</code> Django exception.</p>
<p>Raised when a resource does not exist at the given URL. This exception is equivalent to the standard <code>Http404</code> Django exception.</p>
<p>By default this exception results in a response with the HTTP status code "404 Not Found".</p>
<h2 id="methodnotallowed"><a class="toclink" href="#methodnotallowed">MethodNotAllowed</a></h2>
<p><strong>Signature:</strong> <code>MethodNotAllowed(method, detail=None, code=None)</code></p>
Expand All @@ -668,10 +664,9 @@ <h2 id="throttled"><a class="toclink" href="#throttled">Throttled</a></h2>
<p>Raised when an incoming request fails the throttling checks.</p>
<p>By default this exception results in a response with the HTTP status code "429 Too Many Requests".</p>
<h2 id="validationerror"><a class="toclink" href="#validationerror">ValidationError</a></h2>
<p><strong>Signature:</strong> <code>ValidationError(detail, code=None)</code></p>
<p><strong>Signature:</strong> <code>ValidationError(detail=None, code=None)</code></p>
<p>The <code>ValidationError</code> exception is slightly different from the other <code>APIException</code> classes:</p>
<ul>
<li>The <code>detail</code> argument is mandatory, not optional.</li>
<li>The <code>detail</code> argument may be a list or dictionary of error details, and may also be a nested data structure. By using a dictionary, you can specify field-level errors while performing object-level validation in the <code>validate()</code> method of a serializer. For example. <code>raise serializers.ValidationError({'name': 'Please enter a valid name.'})</code></li>
<li>By convention you should import the serializers module and use a fully qualified <code>ValidationError</code> style, in order to differentiate it from Django's built-in validation error. For example. <code>raise serializers.ValidationError('This field must be an integer value.')</code></li>
</ul>
Expand Down
Loading

0 comments on commit 5796b1a

Please sign in to comment.