From ed1375485906f261449b92fe6e20715530625d07 Mon Sep 17 00:00:00 2001 From: Michael Elovskikh Date: Thu, 17 Jan 2013 17:17:53 +0600 Subject: Added PATCH HTTP method to the docs --- docs/api-guide/authentication.md | 2 +- docs/api-guide/requests.md | 4 ++-- docs/api-guide/views.md | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/api-guide') diff --git a/docs/api-guide/authentication.md b/docs/api-guide/authentication.md index afd9a261..2d34d788 100644 --- a/docs/api-guide/authentication.md +++ b/docs/api-guide/authentication.md @@ -134,7 +134,7 @@ If successfully authenticated, `SessionAuthentication` provides the following cr * `request.user` will be a Django `User` instance. * `request.auth` will be `None`. -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 `PUT`, `POST` or `DELETE` requests. See the [Django CSRF documentation][csrf-ajax] for more details. +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 `PUT`, `PATCH`, `POST` or `DELETE` requests. See the [Django CSRF documentation][csrf-ajax] for more details. # Custom authentication diff --git a/docs/api-guide/requests.md b/docs/api-guide/requests.md index 72932f5d..39a34fcf 100644 --- a/docs/api-guide/requests.md +++ b/docs/api-guide/requests.md @@ -83,13 +83,13 @@ You won't typically need to access this property. # Browser enhancements -REST framework supports a few browser enhancements such as browser-based `PUT` and `DELETE` forms. +REST framework supports a few browser enhancements such as browser-based `PUT`, `PATCH` and `DELETE` forms. ## .method `request.method` returns the **uppercased** string representation of the request's HTTP method. -Browser-based `PUT` and `DELETE` forms are transparently supported. +Browser-based `PUT`, `PATCH` and `DELETE` forms are transparently supported. For more information see the [browser enhancements documentation]. diff --git a/docs/api-guide/views.md b/docs/api-guide/views.md index d1e42ec1..574020f9 100644 --- a/docs/api-guide/views.md +++ b/docs/api-guide/views.md @@ -85,7 +85,7 @@ The following methods are called before dispatching to the handler method. ## Dispatch methods The following methods are called directly by the view's `.dispatch()` method. -These perform any actions that need to occur before or after calling the handler methods such as `.get()`, `.post()`, `put()` and `.delete()`. +These perform any actions that need to occur before or after calling the handler methods such as `.get()`, `.post()`, `put()`, `patch()` and `.delete()`. ### .initial(self, request, \*args, **kwargs) -- cgit v1.2.3 From a7479e02faf37da8987d5933d8c259b045ef1be8 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Sun, 27 Jan 2013 17:23:56 +0000 Subject: AJAX, CSRF & CORS documentation --- docs/api-guide/renderers.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'docs/api-guide') diff --git a/docs/api-guide/renderers.md b/docs/api-guide/renderers.md index b4f7ec3d..4c1fdc53 100644 --- a/docs/api-guide/renderers.md +++ b/docs/api-guide/renderers.md @@ -80,7 +80,7 @@ Renders the request data into `JSONP`. The `JSONP` media type provides a mechan The javascript callback function must be set by the client including a `callback` URL query parameter. For example `http://example.com/api/users?callback=jsonpCallback`. If the callback function is not explicitly set by the client it will default to `'callback'`. -**Note**: If you require cross-domain AJAX requests, you may also want to consider using [CORS] as an alternative to `JSONP`. +**Note**: If you require cross-domain AJAX requests, you may want to consider using the more modern approach of [CORS][cors] as an alternative to `JSONP`. See the [CORS documentation][cors-docs] for more details. **.media_type**: `application/javascript` @@ -288,7 +288,8 @@ Comma-separated values are a plain-text tabular data format, that can be easily [cite]: https://docs.djangoproject.com/en/dev/ref/template-response/#the-rendering-process [conneg]: content-negotiation.md [browser-accept-headers]: http://www.gethifi.com/blog/browser-rest-http-accept-headers -[CORS]: http://en.wikipedia.org/wiki/Cross-origin_resource_sharing +[cors]: http://www.w3.org/TR/cors/ +[cors-docs]: ../topics/ajax-csrf-cors.md [HATEOAS]: http://timelessrepo.com/haters-gonna-hateoas [quote]: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven [application/vnd.github+json]: http://developer.github.com/v3/media/ -- cgit v1.2.3 From 84a33b0a1f89047a24af6845600cccd982bc2baf Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Mon, 28 Jan 2013 07:29:50 +0000 Subject: Example custome permission. Fixes #299. --- docs/api-guide/permissions.md | 9 +++++++++ 1 file changed, 9 insertions(+) (limited to 'docs/api-guide') diff --git a/docs/api-guide/permissions.md b/docs/api-guide/permissions.md index fce68f6d..1814b811 100644 --- a/docs/api-guide/permissions.md +++ b/docs/api-guide/permissions.md @@ -110,6 +110,15 @@ To implement a custom permission, override `BasePermission` and implement the `. The method should return `True` if the request should be granted access, and `False` otherwise. +## Example + +The following is an example of a permission class that checks the incoming request's IP address against a blacklist, and denies the request if the IP has been blacklisted. + + class BlacklistPermission(permissions.BasePermission): + def has_permission(self, request, view, obj=None): + ip_addr = request.META['REMOTE_ADDR'] + blacklisted = Blacklist.objects.filter(ip_addr=ip_addr).exists() + return not blacklisted [cite]: https://developer.apple.com/library/mac/#documentation/security/Conceptual/AuthenticationAndAuthorizationGuide/Authorization/Authorization.html [authentication]: authentication.md -- cgit v1.2.3 From cb219fa04f6a4d4ae0d99920380416f62126b87d Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Mon, 28 Jan 2013 07:30:28 +0000 Subject: Example custom throttle. Fixes #300. --- docs/api-guide/throttling.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) (limited to 'docs/api-guide') diff --git a/docs/api-guide/throttling.md b/docs/api-guide/throttling.md index b03bc9e0..86b1fe8d 100644 --- a/docs/api-guide/throttling.md +++ b/docs/api-guide/throttling.md @@ -150,8 +150,16 @@ User requests to either `ContactListView` or `ContactDetailView` would be restri # Custom throttles -To create a custom throttle, override `BaseThrottle` and implement `.allow_request(request, view)`. The method should return `True` if the request should be allowed, and `False` otherwise. +To create a custom throttle, override `BaseThrottle` and implement `.allow_request(self, request, view)`. The method should return `True` if the request should be allowed, and `False` otherwise. Optionally you may also override the `.wait()` method. If implemented, `.wait()` should return a recommended number of seconds to wait before attempting the next request, or `None`. The `.wait()` method will only be called if `.allow_request()` has previously returned `False`. +## Example + +The following example will randomly throttle 1 in every 10 requests. + + class RandomRateThrottle(throttles.BaseThrottle): + def allow_request(self, request, view): + return random.randint(1, 10) == 1 + [permissions]: permissions.md -- cgit v1.2.3 From e649f2ec61a51beddf56132b3f9fa0a3d4fe086b Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Mon, 28 Jan 2013 07:36:57 +0000 Subject: Example custom authentication. Fixes #301. --- docs/api-guide/authentication.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) (limited to 'docs/api-guide') diff --git a/docs/api-guide/authentication.md b/docs/api-guide/authentication.md index ac690bdc..1795cfaf 100644 --- a/docs/api-guide/authentication.md +++ b/docs/api-guide/authentication.md @@ -194,6 +194,24 @@ You *may* also override the `.authentication_header(self, request)` method. If If the `.authentication_header()` method is not overridden, the authentication scheme will return `HTTP 403 Forbidden` responses when an unauthenticated request is denied access. +## Example + +The following example will authenticate any incoming request as the user given by the username in a custom request header named 'X_USERNAME'. + + class ExampleAuthentication(authentication.BaseAuthentication): + def has_permission(self, request, view, obj=None): + username = request.META.get('X_USERNAME') + if not username: + return None + + try: + user = User.objects.get(username=username) + except User.DoesNotExist: + raise authenticate.AuthenticationFailed('No such user') + + return (user, None) + + [cite]: http://jacobian.org/writing/rest-worst-practices/ [http401]: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2 [http403]: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4 -- cgit v1.2.3 From 99ef0bcad994ba472882cd67a5c7d8c9b77554bf Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Mon, 28 Jan 2013 07:37:15 +0000 Subject: Tweak description of example throttle. --- docs/api-guide/throttling.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/api-guide') diff --git a/docs/api-guide/throttling.md b/docs/api-guide/throttling.md index 86b1fe8d..923593bc 100644 --- a/docs/api-guide/throttling.md +++ b/docs/api-guide/throttling.md @@ -156,7 +156,7 @@ Optionally you may also override the `.wait()` method. If implemented, `.wait() ## Example -The following example will randomly throttle 1 in every 10 requests. +The following is an example of a rate throttle, that will randomly throttle 1 in every 10 requests. class RandomRateThrottle(throttles.BaseThrottle): def allow_request(self, request, view): -- cgit v1.2.3 From a58145e20f796232ef0143f28ecb0c31dbfea92e Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Mon, 28 Jan 2013 07:46:30 +0000 Subject: Note auto_now, auto_now_add behavior. Refs #622. --- docs/api-guide/fields.md | 10 ++++++++++ 1 file changed, 10 insertions(+) (limited to 'docs/api-guide') diff --git a/docs/api-guide/fields.md b/docs/api-guide/fields.md index 5bc8f7f7..e43282ce 100644 --- a/docs/api-guide/fields.md +++ b/docs/api-guide/fields.md @@ -193,6 +193,16 @@ A date and time representation. Corresponds to `django.db.models.fields.DateTimeField` +When using `ModelSerializer` or `HyperlinkedModelSerializer`, note that any model fields with `auto_now=True` or `auto_now_add=True` will use serializer fields that are `read_only=True` by default. + +If you want to override this behavior, you'll need to declare the `DateTimeField` explicitly on the serializer. For example: + + class CommentSerializer(serializers.ModelSerializer): + created = serializers.DateTimeField() + + class Meta: + model = Comment + ## IntegerField An integer representation. -- cgit v1.2.3 From e682bfa54efc391df4d6bb7cf78a2089213b8d6b Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Mon, 28 Jan 2013 08:01:54 +0000 Subject: Drop unneccessary `source=` argument. --- docs/api-guide/relations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/api-guide') diff --git a/docs/api-guide/relations.md b/docs/api-guide/relations.md index 351b5e09..9f5a04b2 100644 --- a/docs/api-guide/relations.md +++ b/docs/api-guide/relations.md @@ -67,7 +67,7 @@ For example, given the following models: And a model serializer defined like this: class BookmarkSerializer(serializers.ModelSerializer): - tags = serializers.ManyRelatedField(source='tags') + tags = serializers.ManyRelatedField() class Meta: model = Bookmark -- cgit v1.2.3 From 661c8f9ad56a1f5f35e4a769ac44b668227b14e6 Mon Sep 17 00:00:00 2001 From: swistakm Date: Mon, 28 Jan 2013 13:05:52 +0100 Subject: fix mistake in docs --- docs/api-guide/authentication.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/api-guide') diff --git a/docs/api-guide/authentication.md b/docs/api-guide/authentication.md index da494746..59afc2b9 100644 --- a/docs/api-guide/authentication.md +++ b/docs/api-guide/authentication.md @@ -190,9 +190,9 @@ Typically the approach you should take is: * If authentication is not attempted, return `None`. Any other authentication schemes also in use will still be checked. * If authentication is attempted but fails, raise a `AuthenticationFailed` exception. An error response will be returned immediately, without checking any other authentication schemes. -You *may* also override the `.authentication_header(self, request)` method. If implemented, it should return a string that will be used as the value of the `WWW-Authenticate` header in a `HTTP 401 Unauthorized` response. +You *may* also override the `.authenticate_header(self, request)` method. If implemented, it should return a string that will be used as the value of the `WWW-Authenticate` header in a `HTTP 401 Unauthorized` response. -If the `.authentication_header()` method is not overridden, the authentication scheme will return `HTTP 403 Forbidden` responses when an unauthenticated request is denied access. +If the `.authenticate_header()` method is not overridden, the authentication scheme will return `HTTP 403 Forbidden` responses when an unauthenticated request is denied access. ## Example -- cgit v1.2.3 From 1929159db1b45ef28d1f7fdf0bea9d0867af13f3 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Tue, 29 Jan 2013 09:15:08 +0000 Subject: Docs tweaks. --- docs/api-guide/fields.md | 4 +++- docs/api-guide/serializers.md | 12 +++--------- 2 files changed, 6 insertions(+), 10 deletions(-) (limited to 'docs/api-guide') diff --git a/docs/api-guide/fields.md b/docs/api-guide/fields.md index e43282ce..3f8a36e2 100644 --- a/docs/api-guide/fields.md +++ b/docs/api-guide/fields.md @@ -240,7 +240,9 @@ Signature and validation is the same as with `FileField`. --- **Note:** `FileFields` and `ImageFields` are only suitable for use with MultiPartParser, since e.g. json doesn't support file uploads. -Django's regular [FILE_UPLOAD_HANDLERS] are used for handling uploaded files. +Django's regular [FILE_UPLOAD_HANDLERS] are used for handling uploaded files. + +--- [cite]: https://docs.djangoproject.com/en/dev/ref/forms/api/#django.forms.Form.cleaned_data [FILE_UPLOAD_HANDLERS]: https://docs.djangoproject.com/en/dev/ref/settings/#std:setting-FILE_UPLOAD_HANDLERS diff --git a/docs/api-guide/serializers.md b/docs/api-guide/serializers.md index d98a602f..487502e9 100644 --- a/docs/api-guide/serializers.md +++ b/docs/api-guide/serializers.md @@ -190,18 +190,12 @@ By default field values are treated as mapping to an attribute on the object. I As an example, let's create a field that can be used represent the class name of the object being serialized: - class ClassNameField(serializers.WritableField): + class ClassNameField(serializers.Field): def field_to_native(self, obj, field_name): """ - Serialize the object's class name, not an attribute of the object. + Serialize the object's class name. """ - return obj.__class__.__name__ - - def field_from_native(self, data, field_name, into): - """ - We don't want to set anything when we revert this field. - """ - pass + return obj.__class__ --- -- cgit v1.2.3