diff options
Diffstat (limited to 'api-guide')
| -rw-r--r-- | api-guide/authentication/index.html | 2 | ||||
| -rw-r--r-- | api-guide/fields/index.html | 31 | ||||
| -rw-r--r-- | api-guide/filtering/index.html | 6 | ||||
| -rw-r--r-- | api-guide/routers/index.html | 6 | ||||
| -rw-r--r-- | api-guide/viewsets/index.html | 2 |
5 files changed, 36 insertions, 11 deletions
diff --git a/api-guide/authentication/index.html b/api-guide/authentication/index.html index ac8f4629..7a523c63 100644 --- a/api-guide/authentication/index.html +++ b/api-guide/authentication/index.html @@ -648,7 +648,7 @@ python manage.py createsuperuser <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/dev/ref/contrib/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/dev/ref/csrf/#ajax">Django CSRF documentation</a> for more details.</p> <h2 id="oauthauthentication">OAuthAuthentication</h2> <p>This authentication uses <a href="http://oauth.net/core/1.0a">OAuth 1.0a</a> authentication scheme. OAuth 1.0a provides signature validation which provides a reasonable level of security over plain non-HTTPS connections. However, it may also be considered more complicated than OAuth2, as it requires clients to sign their requests.</p> <p>This authentication class depends on the optional <code>django-oauth-plus</code> and <code>oauth2</code> packages. In order to make it work you must install these packages and add <code>oauth_provider</code> to your <code>INSTALLED_APPS</code>:</p> diff --git a/api-guide/fields/index.html b/api-guide/fields/index.html index 9cac530a..83affe26 100644 --- a/api-guide/fields/index.html +++ b/api-guide/fields/index.html @@ -405,6 +405,10 @@ <a href="#urlfield">URLField</a> </li> + <li> + <a href="#uuidfield">UUIDField</a> + </li> + @@ -493,6 +497,10 @@ <a href="#listfield">ListField</a> </li> + <li> + <a href="#dictfield">DictField</a> + </li> + @@ -674,6 +682,10 @@ color_channel = serializers.ChoiceField( <p>A <code>RegexField</code> that validates the input against a URL matching pattern. Expects fully qualified URLs of the form <code>http://<host>/<path></code>.</p> <p>Corresponds to <code>django.db.models.fields.URLField</code>. Uses Django's <code>django.core.validators.URLValidator</code> for validation.</p> <p><strong>Signature:</strong> <code>URLField(max_length=200, min_length=None, allow_blank=False)</code></p> +<h2 id="uuidfield">UUIDField</h2> +<p>A field that ensures the input is a valid UUID string. The <code>to_internal_value</code> method will return a <code>uuid.UUID</code> instance. On output the field will return a string in the canonical hyphenated format, for example:</p> +<pre><code>"de305d54-75b4-431b-adb2-eb6b9e546013" +</code></pre> <hr /> <h1 id="numeric-fields">Numeric fields</h1> <h2 id="integerfield">IntegerField</h2> @@ -767,7 +779,7 @@ color_channel = serializers.ChoiceField( </ul> <p>Both the <code>allow_blank</code> and <code>allow_null</code> are valid options on <code>ChoiceField</code>, although it is highly recommended that you only use one and not both. <code>allow_blank</code> should be preferred for textual choices, and <code>allow_null</code> should be preferred for numeric or other non-textual choices.</p> <h2 id="multiplechoicefield">MultipleChoiceField</h2> -<p>A field that can accept a set of zero, one or many values, chosen from a limited set of choices. Takes a single mandatory argument. <code>to_internal_representation</code> returns a <code>set</code> containing the selected values.</p> +<p>A field that can accept a set of zero, one or many values, chosen from a limited set of choices. Takes a single mandatory argument. <code>to_internal_value</code> returns a <code>set</code> containing the selected values.</p> <p><strong>Signature:</strong> <code>MultipleChoiceField(choices)</code></p> <ul> <li><code>choices</code> - A list of valid values, or a list of <code>(key, display_name)</code> tuples.</li> @@ -804,7 +816,7 @@ Django's regular <a href="https://docs.djangoproject.com/en/dev/ref/settings/#st <p>A field class that validates a list of objects.</p> <p><strong>Signature</strong>: <code>ListField(child)</code></p> <ul> -<li><code>child</code> - A field instance that should be used for validating the objects in the list.</li> +<li><code>child</code> - A field instance that should be used for validating the objects in the list. If this argument is not provided then objects in the list will not be validated.</li> </ul> <p>For example, to validate a list of integers you might use something like the following:</p> <pre><code>scores = serializers.ListField( @@ -816,6 +828,19 @@ Django's regular <a href="https://docs.djangoproject.com/en/dev/ref/settings/#st child = serializers.CharField() </code></pre> <p>We can now reuse our custom <code>StringListField</code> class throughout our application, without having to provide a <code>child</code> argument to it.</p> +<h2 id="dictfield">DictField</h2> +<p>A field class that validates a dictionary of objects. The keys in <code>DictField</code> are always assumed to be string values.</p> +<p><strong>Signature</strong>: <code>DictField(child)</code></p> +<ul> +<li><code>child</code> - A field instance that should be used for validating the values in the dictionary. If this argument is not provided then values in the mapping will not be validated.</li> +</ul> +<p>For example, to create a field that validates a mapping of strings to strings, you would write something like this:</p> +<pre><code>document = DictField(child=CharField()) +</code></pre> +<p>You can also use the declarative style, as with <code>ListField</code>. For example:</p> +<pre><code>class DocumentField(DictField): + child = CharField() +</code></pre> <hr /> <h1 id="miscellaneous-fields">Miscellaneous fields</h1> <h2 id="readonlyfield">ReadOnlyField</h2> @@ -845,7 +870,7 @@ Django's regular <a href="https://docs.djangoproject.com/en/dev/ref/settings/#st <p>This is a read-only field. It gets its value by calling a method on the serializer class it is attached to. It can be used to add any sort of data to the serialized representation of your object.</p> <p><strong>Signature</strong>: <code>SerializerMethodField(method_name=None)</code></p> <ul> -<li><code>method-name</code> - The name of the method on the serializer to be called. If not included this defaults to <code>get_<field_name></code>.</li> +<li><code>method_name</code> - The name of the method on the serializer to be called. If not included this defaults to <code>get_<field_name></code>.</li> </ul> <p>The serializer method referred to by the <code>method_name</code> argument should accept a single argument (in addition to <code>self</code>), which is the object being serialized. It should return whatever you want to be included in the serialized representation of the object. For example:</p> <pre><code>from django.contrib.auth.models import User diff --git a/api-guide/filtering/index.html b/api-guide/filtering/index.html index fa0a15f8..374c0a5d 100644 --- a/api-guide/filtering/index.html +++ b/api-guide/filtering/index.html @@ -434,7 +434,7 @@ <li> - <a href="#django-rest-framework-chain">Django REST framework chain</a> + <a href="#django-rest-framework-filters-package">Django REST framework filters package</a> </li> @@ -757,8 +757,8 @@ class ProductFilter(django_filters.FilterSet): <p>We could achieve the same behavior by overriding <code>get_queryset()</code> on the views, but using a filter backend allows you to more easily add this restriction to multiple views, or to apply it across the entire API.</p> <h1 id="third-party-packages">Third party packages</h1> <p>The following third party packages provide additional filter implementations.</p> -<h2 id="django-rest-framework-chain">Django REST framework chain</h2> -<p>The <a href="https://github.com/philipn/django-rest-framework-chain">django-rest-framework-chain package</a> works together with the <code>DjangoFilterBackend</code> class, and allows you to easily create filters across relationships, or create multiple filter lookup types for a given field.</p> +<h2 id="django-rest-framework-filters-package">Django REST framework filters package</h2> +<p>The <a href="https://github.com/philipn/django-rest-framework-filters">django-rest-framework-filters package</a> works together with the <code>DjangoFilterBackend</code> class, and allows you to easily create filters across relationships, or create multiple filter lookup types for a given field.</p> </div> <!--/span--> diff --git a/api-guide/routers/index.html b/api-guide/routers/index.html index 70d136f4..cc7bad73 100644 --- a/api-guide/routers/index.html +++ b/api-guide/routers/index.html @@ -483,20 +483,20 @@ router.register(r'users', UserViewSet) router.register(r'accounts', AccountViewSet) urlpatterns = [ - url(r'^forgot-password/$, ForgotPasswordFormView.as_view(), + url(r'^forgot-password/$', ForgotPasswordFormView.as_view(), ] urlpatterns += router.urls </code></pre> <p>Alternatively you can use Django's <code>include</code> function, like so…</p> <pre><code>urlpatterns = [ - url(r'^forgot-password/$, ForgotPasswordFormView.as_view(), + url(r'^forgot-password/$', ForgotPasswordFormView.as_view(), url(r'^', include(router.urls)) ] </code></pre> <p>Router URL patterns can also be namespaces.</p> <pre><code>urlpatterns = [ - url(r'^forgot-password/$, ForgotPasswordFormView.as_view(), + url(r'^forgot-password/$', ForgotPasswordFormView.as_view(), url(r'^api/', include(router.urls, namespace='api')) ] </code></pre> diff --git a/api-guide/viewsets/index.html b/api-guide/viewsets/index.html index d8cd2526..13debab3 100644 --- a/api-guide/viewsets/index.html +++ b/api-guide/viewsets/index.html @@ -548,7 +548,7 @@ class UserViewSet(viewsets.ModelViewSet): def set_password(self, request, pk=None): ... </code></pre> -<p>Theses decorators will route <code>GET</code> requests by default, but may also accept other HTTP methods, by using the <code>methods</code> argument. For example:</p> +<p>These decorators will route <code>GET</code> requests by default, but may also accept other HTTP methods, by using the <code>methods</code> argument. For example:</p> <pre><code> @detail_route(methods=['post', 'delete']) def unset_password(self, request, pk=None): ... |