@@ -481,6 +482,8 @@ class ExampleAuthentication(authentication.BaseAuthentication):
<p>The <ahref="https://github.com/Rediker-Software/doac">Django OAuth2 Consumer</a> library from <ahref="https://github.com/Rediker-Software">Rediker Software</a> is another package that provides <ahref="https://github.com/Rediker-Software/doac/blob/master/docs/integrations.md#">OAuth 2.0 support for REST framework</a>. The package includes token scoping permissions on tokens, which allows finer-grained access to your API.</p>
<h2id="json-web-token-authentication">JSON Web Token Authentication</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. <ahref="https://github.com/GetBlimp">Blimp</a> maintains the <ahref="https://github.com/GetBlimp/django-rest-framework-jwt">djangorestframework-jwt</a> package which provides a JWT Authentication class as well as a mechanism for clients to obtain a JWT given the username and password.</p>
<p>HTTP Signature (currently a <ahref="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 <ahref="http://docs.aws.amazon.com/general/latest/gr/signature-version-4.html">Amazon's HTTP Signature scheme</a>, used by many of its services, it permits stateless, per-request authentication. <ahref="https://github.com/etoccalino/">Elvio Toccalino</a> maintains the <ahref="https://github.com/etoccalino/django-rest-framework-httpsignature">djangorestframework-httpsignature</a> package which provides an easy to use HTTP Signature Authentication mechanism.</p>
<p>In each case, REST framework will return a response with an appropriate status code and content-type. The body of the response will include any additional details regarding the nature of the error.</p>
<p>By default all error responses will include a key <code>details</code> in the body of the response, but other keys may also be included.</p>
<p>By default all error responses will include a key <code>detail</code> in the body of the response, but other keys may also be included.</p>
<p>The <strong>base class</strong> for all exceptions raised inside REST framework.</p>
<p>To provide a custom exception, subclass <code>APIException</code> and set the <code>.status_code</code> and <code>.detail</code> properties on the class.</p>
<p>To provide a custom exception, subclass <code>APIException</code> and set the <code>.status_code</code> and <code>.default_detail</code> properties 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>
@@ -270,6 +270,7 @@ class AccountSerializer(serializers.HyperlinkedModelSerializer):
expired = serializers.Field(source='has_expired')
class Meta:
model = Account
fields = ('url', 'owner', 'name', 'expired')
</code></pre>
<p>Would produce output similar to:</p>
...
...
@@ -285,7 +286,7 @@ class AccountSerializer(serializers.HyperlinkedModelSerializer):
<h2id="writablefield">WritableField</h2>
<p>A field that supports both read and write operations. By itself <code>WritableField</code> does not perform any translation of input values into a given type. You won't typically use this field directly, but you may want to override it and implement the <code>.to_native(self, value)</code> and <code>.from_native(self, value)</code> methods.</p>
<h2id="modelfield">ModelField</h2>
<p>A generic field that can be tied to any arbitrary model field. The <code>ModelField</code> class delegates the task of serialization/deserialization to it's associated model field. This field can be used to create serializer fields for custom model fields, without having to create a new custom serializer field.</p>
<p>A generic field that can be tied to any arbitrary model field. The <code>ModelField</code> class delegates the task of serialization/deserialization to its associated model field. This field can be used to create serializer fields for custom model fields, without having to create a new custom serializer field.</p>
<p>The <code>ModelField</code> class is generally intended for internal use, but can be used by your API if needed. In order to properly instantiate a <code>ModelField</code>, it must be passed a field that is attached to an instantiated model. For example: <code>ModelField(model_field=MyModel()._meta.get_field('custom_field'))</code></p>
<p>If you want to create a custom field, you'll probably want to override either one or both of the <code>.to_native()</code> and <code>.from_native()</code> methods. These two methods are used to convert between the initial datatype, and a primitive, serializable datatype. Primitive datatypes may be any of a number, string, date/time/datetime or None. They may also be any list or dictionary like object that only contains other primitive objects.</p>
<p>The <code>.to_native()</code> method is called to convert the initial datatype into a primitive, serializable datatype. The <code>from_native()</code> method is called to restore a primitive datatype into it's initial representation.</p>
<p>The <code>.to_native()</code> method is called to convert the initial datatype into a primitive, serializable datatype. The <code>from_native()</code> method is called to restore a primitive datatype into its initial representation.</p>
<h2id="examples">Examples</h2>
<p>Let's look at an example of serializing a class that represents an RGB color value:</p>
@@ -299,7 +299,7 @@ class UserList(generics.ListCreateAPIView):
self.check_object_permissions(self.request, obj)
return obj
</code></pre>
<p>Note that if your API doesn't include any object level permissions, you may optionally exclude the <code>`self.check_object_permissions, and simply return the object from the</code>get_object_or_404` lookup.</p>
<p>Note that if your API doesn't include any object level permissions, you may optionally exclude the <code>self.check_object_permissions</code>, and simply return the object from the <code>get_object_or_404</code> lookup.</p>
<p>Returns the classes that should be used to filter the queryset. Defaults to returning the <code>filter_backends</code> attribute.</p>
<p>May be override to provide more complex behavior with filters, as using different (or even exlusive) lists of filter_backends depending on different criteria.</p>
<h1id="third-party-packages">Third party packages</h1>
<p>The following third party packages are also available.</p>
<h2id="drf-extensions">DRF-extensions</h2>
<p>The <ahref="http://chibisov.github.io/drf-extensions/docs/"><code>DRF-extensions</code> package</a> includes a <ahref="http://chibisov.github.io/drf-extensions/docs/#paginatebymaxmixin"><code>PaginateByMaxMixin</code> mixin class</a> that allows your API clients to specify <code>?page_size=max</code> to obtain the maximum allowed page size.</p>
<p>You can add extra fields to a <code>ModelSerializer</code> or override the default fields by declaring fields on the class, just as you would for a <code>Serializer</code> class.</p>
@@ -357,11 +357,11 @@ class AccountTests(APITestCase):
<h1id="testing-responses">Testing responses</h1>
<h2id="checking-the-response-data">Checking the response data</h2>
<p>When checking the validity of test responses it's often more convenient to inspect the data that the response was created with, rather than inspecting the fully rendered response.</p>
<p>For example, it's easier to inspect <code>request.data</code>:</p>
<p>For example, it's easier to inspect <code>response.data</code>:</p>
