From ed1375485906f261449b92fe6e20715530625d07 Mon Sep 17 00:00:00 2001 From: Michael Elovskikh Date: Thu, 17 Jan 2013 17:17:53 +0600 Subject: [PATCH 01/30] 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 +- docs/topics/browsable-api.md | 3 ++- docs/topics/browser-enhancements.md | 8 ++++---- 5 files changed, 10 insertions(+), 9 deletions(-) diff --git a/docs/api-guide/authentication.md b/docs/api-guide/authentication.md index afd9a2619..2d34d7887 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 72932f5d6..39a34fcfb 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 d1e42ec1c..574020f9b 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) diff --git a/docs/topics/browsable-api.md b/docs/topics/browsable-api.md index 9fe82e696..479987a19 100644 --- a/docs/topics/browsable-api.md +++ b/docs/topics/browsable-api.md @@ -5,7 +5,7 @@ > — [Alfred North Whitehead][cite], An Introduction to Mathematics (1911) -API may stand for Application *Programming* Interface, but humans have to be able to read the APIs, too; someone has to do the programming. Django REST Framework supports generating human-friendly HTML output for each resource when the `HTML` format is requested. These pages allow for easy browsing of resources, as well as forms for submitting data to the resources using `POST`, `PUT`, and `DELETE`. +API may stand for Application *Programming* Interface, but humans have to be able to read the APIs, too; someone has to do the programming. Django REST Framework supports generating human-friendly HTML output for each resource when the `HTML` format is requested. These pages allow for easy browsing of resources, as well as forms for submitting data to the resources using `POST`, `PUT`, `PATCH` and `DELETE`. ## URLs @@ -79,6 +79,7 @@ The context that's available to the template: * `name` : The name of the resource * `post_form` : A form instance for use by the POST form (if allowed) * `put_form` : A form instance for use by the PUT form (if allowed) +* `patch_form` : A form instance for use by the PATCH form (if allowed) * `request` : The request object * `response` : The response object * `version` : The version of Django REST Framework diff --git a/docs/topics/browser-enhancements.md b/docs/topics/browser-enhancements.md index 6a11f0fac..3949f7a60 100644 --- a/docs/topics/browser-enhancements.md +++ b/docs/topics/browser-enhancements.md @@ -1,12 +1,12 @@ # Browser enhancements -> "There are two noncontroversial uses for overloaded POST. The first is to *simulate* HTTP's uniform interface for clients like web browsers that don't support PUT or DELETE" +> "There are two noncontroversial uses for overloaded POST. The first is to *simulate* HTTP's uniform interface for clients like web browsers that don't support PUT, PATCH or DELETE" > > — [RESTful Web Services][cite], Leonard Richardson & Sam Ruby. -## Browser based PUT, DELETE, etc... +## Browser based PUT, PATCH, DELETE, etc... -REST framework supports browser-based `PUT`, `DELETE` and other methods, by +REST framework supports browser-based `PUT`, `PATCH`, `DELETE` and other methods, by overloading `POST` requests using a hidden form field. Note that this is the same strategy as is used in [Ruby on Rails][rails]. @@ -51,7 +51,7 @@ the view. This is a more concise than using the `accept` override, but it also gives you less control. (For example you can't specify any media type parameters) -## Doesn't HTML5 support PUT and DELETE forms? +## Doesn't HTML5 support PUT, PATCH and DELETE forms? Nope. It was at one point intended to support `PUT` and `DELETE` forms, but was later [dropped from the spec][html5]. There remains From a7479e02faf37da8987d5933d8c259b045ef1be8 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Sun, 27 Jan 2013 17:23:56 +0000 Subject: [PATCH 02/30] AJAX, CSRF & CORS documentation --- docs/api-guide/renderers.md | 5 +++-- docs/index.md | 3 ++- docs/template.html | 1 + docs/topics/ajax-csrf-cors.md | 41 +++++++++++++++++++++++++++++++++++ docs/topics/csrf.md | 12 ---------- 5 files changed, 47 insertions(+), 15 deletions(-) create mode 100644 docs/topics/ajax-csrf-cors.md delete mode 100644 docs/topics/csrf.md diff --git a/docs/api-guide/renderers.md b/docs/api-guide/renderers.md index b4f7ec3d4..4c1fdc53b 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/ diff --git a/docs/index.md b/docs/index.md index 05c68b253..453a67b8a 100644 --- a/docs/index.md +++ b/docs/index.md @@ -117,6 +117,7 @@ The API guide is your complete reference manual to all the functionality provide General guides to using REST framework. +* [AJAX, CSRF & CORS][ajax-csrf-cors] * [Browser enhancements][browser-enhancements] * [The Browsable API][browsableapi] * [REST, Hypermedia & HATEOAS][rest-hypermedia-hateoas] @@ -210,7 +211,7 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. [status]: api-guide/status-codes.md [settings]: api-guide/settings.md -[csrf]: topics/csrf.md +[ajax-csrf-cors]: topics/ajax-csrf-cors.md [browser-enhancements]: topics/browser-enhancements.md [browsableapi]: topics/browsable-api.md [rest-hypermedia-hateoas]: topics/rest-hypermedia-hateoas.md diff --git a/docs/template.html b/docs/template.html index d789cc582..2a87e92ba 100644 --- a/docs/template.html +++ b/docs/template.html @@ -89,6 +89,7 @@
  • Topics
      +
    • AJAX, CSRF & CORS
    • Browser enhancements
    • The Browsable API
    • REST, Hypermedia & HATEOAS
      • diff --git a/docs/topics/ajax-csrf-cors.md b/docs/topics/ajax-csrf-cors.md new file mode 100644 index 000000000..b7e5dff63 --- /dev/null +++ b/docs/topics/ajax-csrf-cors.md @@ -0,0 +1,41 @@ +# Working with AJAX, CSRF & CORS + +> "Take a close look at possible CSRF / XSRF vulnerabilities on your own websites. They're the worst kind of vulnerability — very easy to exploit by attackers, yet not so intuitively easy to understand for software developers, at least until you've been bitten by one." +> +> — [Jeff Atwood][cite] + +## Javascript clients + +If your building a javascript client to interface with your Web API, you'll need to consider if the client can use the same authentication policy that is used by the rest of the website, and also determine if you need to use CSRF tokens or CORS headers. + +AJAX requests that are made within the same context as the API they are interacting with will typically use `SessionAuthentication`. This ensures that once a user has logged in, any AJAX requests made can be authenticated using the same session-based authentication that is used for the rest of the website. + +AJAX requests that are made on a different site from the API they are communicating with will typically need to use a non-session-based authentication scheme, such as `TokenAuthentication`. + +## CSRF protection + +[Cross Site Request Forgery][csrf] protection is a mechanism of guarding against a particular type of attack, which can occur when a user has not logged out of a web site, and continues to have a valid session. In this circumstance a malicious site may be able to perform actions against the target site, within the cotext of the logged-in session. + +To guard against these type of attacks, you need to do two things: + +1. Ensure that the 'safe' HTTP operations, such as `GET`, `HEAD` and `OPTIONS` cannot be used to alter any server-side state. +2. Ensure that any 'unsafe' HTTP operations, such as `POST`, `PUT`, `PATCH` and `DELETE`, always require a valid CSRF token. + +If you're using `SessionAuthentication` you'll need to include valid CSRF tokens for any `POST`, `PUT`, `PATCH` or `DELETE` operations. + +The Django documentation describes how to [include CSRF tokens in AJAX requests][csrf-ajax]. + +## CORS + +[Cross-Origin Resource Sharing][cors] is a mechanism for allowing clients to interact with APIs that are hosted on a different domain. CORS works by requiring the server to include a specific set of headers that allow a browser to determine if and when cross-domain requests should be allowed. + +The best way to deal with CORS in REST framework is to add the required response headers in middleware. This ensures that CORS is supported transparently, without having to change any behavior in your views. + +[Otto Yiu][ottoyiu] maintains the [django-cors-headers] package, which is known to work correctly with REST framework APIs. + +[cite]: http://www.codinghorror.com/blog/2008/10/preventing-csrf-and-xsrf-attacks.html +[csrf]: https://www.owasp.org/index.php/Cross-Site_Request_Forgery_(CSRF) +[csrf-ajax]: http://djangoproject.com/en/dev/ref/contrib/csrf/#ajax +[cors]: http://www.w3.org/TR/cors/ +[ottoyiu]: https://github.com/ottoyiu/ +[django-cors-headers]: https://github.com/ottoyiu/django-cors-headers/ diff --git a/docs/topics/csrf.md b/docs/topics/csrf.md deleted file mode 100644 index 043144c1b..000000000 --- a/docs/topics/csrf.md +++ /dev/null @@ -1,12 +0,0 @@ -# Working with AJAX and CSRF - -> "Take a close look at possible CSRF / XSRF vulnerabilities on your own websites. They're the worst kind of vulnerability -- very easy to exploit by attackers, yet not so intuitively easy to understand for software developers, at least until you've been bitten by one." -> -> — [Jeff Atwood][cite] - -* Explain need to add CSRF token to AJAX requests. -* Explain deferred CSRF style used by REST framework -* Why you should use Django's standard login/logout views, and not REST framework view - - -[cite]: http://www.codinghorror.com/blog/2008/10/preventing-csrf-and-xsrf-attacks.html From d4f38dece44d0d57c1eb71584807219e6e893055 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Sun, 27 Jan 2013 17:32:54 +0000 Subject: [PATCH 03/30] Fix link to django docs. --- docs/topics/ajax-csrf-cors.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/topics/ajax-csrf-cors.md b/docs/topics/ajax-csrf-cors.md index b7e5dff63..a96d6ac51 100644 --- a/docs/topics/ajax-csrf-cors.md +++ b/docs/topics/ajax-csrf-cors.md @@ -35,7 +35,7 @@ The best way to deal with CORS in REST framework is to add the required response [cite]: http://www.codinghorror.com/blog/2008/10/preventing-csrf-and-xsrf-attacks.html [csrf]: https://www.owasp.org/index.php/Cross-Site_Request_Forgery_(CSRF) -[csrf-ajax]: http://djangoproject.com/en/dev/ref/contrib/csrf/#ajax +[csrf-ajax]: https://docs.djangoproject.com/en/dev/ref/contrib/csrf/#ajax [cors]: http://www.w3.org/TR/cors/ [ottoyiu]: https://github.com/ottoyiu/ [django-cors-headers]: https://github.com/ottoyiu/django-cors-headers/ From ccb4ef081191bb8fa3d76d698d61190c1d9c3f65 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Sun, 27 Jan 2013 19:34:16 +0000 Subject: [PATCH 04/30] Typo --- docs/topics/ajax-csrf-cors.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/topics/ajax-csrf-cors.md b/docs/topics/ajax-csrf-cors.md index a96d6ac51..f7d12940d 100644 --- a/docs/topics/ajax-csrf-cors.md +++ b/docs/topics/ajax-csrf-cors.md @@ -14,7 +14,7 @@ AJAX requests that are made on a different site from the API they are communicat ## CSRF protection -[Cross Site Request Forgery][csrf] protection is a mechanism of guarding against a particular type of attack, which can occur when a user has not logged out of a web site, and continues to have a valid session. In this circumstance a malicious site may be able to perform actions against the target site, within the cotext of the logged-in session. +[Cross Site Request Forgery][csrf] protection is a mechanism of guarding against a particular type of attack, which can occur when a user has not logged out of a web site, and continues to have a valid session. In this circumstance a malicious site may be able to perform actions against the target site, within the context of the logged-in session. To guard against these type of attacks, you need to do two things: From c1dc1860da86dc119f2e80837c6b327af12b9b38 Mon Sep 17 00:00:00 2001 From: Mike TUMS Date: Mon, 28 Jan 2013 00:32:32 +0400 Subject: [PATCH 05/30] Update docs/tutorial/1-serialization.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Update for tutorials (manual serialization) to support HTTP PATCH method (partial update of instance) --- docs/tutorial/1-serialization.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/tutorial/1-serialization.md b/docs/tutorial/1-serialization.md index f5ff167f0..d66d2b97c 100644 --- a/docs/tutorial/1-serialization.md +++ b/docs/tutorial/1-serialization.md @@ -129,12 +129,12 @@ The first thing we need to get started on our Web API is provide a way of serial Create or update a new snippet instance. """ if instance: - # Update existing instance - instance.title = attrs['title'] - instance.code = attrs['code'] - instance.linenos = attrs['linenos'] - instance.language = attrs['language'] - instance.style = attrs['style'] + # Update existing instance or part of it + instance.title = attrs.get('title', instance.title) + instance.code = attrs.get('code', instance.code) + instance.linenos = attrs.get('linenos', instance.linenos) + instance.language = attrs.get('language', instance.language) + instance.style = attrs.get('style', instance.style) return instance # Create new instance From 84a33b0a1f89047a24af6845600cccd982bc2baf Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Mon, 28 Jan 2013 07:29:50 +0000 Subject: [PATCH 06/30] Example custome permission. Fixes #299. --- docs/api-guide/permissions.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/api-guide/permissions.md b/docs/api-guide/permissions.md index fce68f6db..1814b8110 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 From cb219fa04f6a4d4ae0d99920380416f62126b87d Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Mon, 28 Jan 2013 07:30:28 +0000 Subject: [PATCH 07/30] Example custom throttle. Fixes #300. --- docs/api-guide/throttling.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/docs/api-guide/throttling.md b/docs/api-guide/throttling.md index b03bc9e04..86b1fe8d8 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 From e649f2ec61a51beddf56132b3f9fa0a3d4fe086b Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Mon, 28 Jan 2013 07:36:57 +0000 Subject: [PATCH 08/30] Example custom authentication. Fixes #301. --- docs/api-guide/authentication.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/docs/api-guide/authentication.md b/docs/api-guide/authentication.md index ac690bdc0..1795cfaf1 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 From 99ef0bcad994ba472882cd67a5c7d8c9b77554bf Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Mon, 28 Jan 2013 07:37:15 +0000 Subject: [PATCH 09/30] Tweak description of example throttle. --- docs/api-guide/throttling.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api-guide/throttling.md b/docs/api-guide/throttling.md index 86b1fe8d8..923593bcc 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): From a58145e20f796232ef0143f28ecb0c31dbfea92e Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Mon, 28 Jan 2013 07:46:30 +0000 Subject: [PATCH 10/30] Note auto_now, auto_now_add behavior. Refs #622. --- docs/api-guide/fields.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/api-guide/fields.md b/docs/api-guide/fields.md index 5bc8f7f7c..e43282ce3 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. From b11628f429a241120c37981a17bbc375c23bb7ee Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Mon, 28 Jan 2013 07:52:04 +0000 Subject: [PATCH 11/30] Revert comment. --- docs/tutorial/1-serialization.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorial/1-serialization.md b/docs/tutorial/1-serialization.md index d66d2b97c..03c7ad717 100644 --- a/docs/tutorial/1-serialization.md +++ b/docs/tutorial/1-serialization.md @@ -129,7 +129,7 @@ The first thing we need to get started on our Web API is provide a way of serial Create or update a new snippet instance. """ if instance: - # Update existing instance or part of it + # Update existing instance instance.title = attrs.get('title', instance.title) instance.code = attrs.get('code', instance.code) instance.linenos = attrs.get('linenos', instance.linenos) From b1ae82b498b51f898ef6c767a5280c5db57c8afc Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Mon, 28 Jan 2013 07:52:22 +0000 Subject: [PATCH 12/30] And link to quickstart. --- docs/tutorial/1-serialization.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorial/1-serialization.md b/docs/tutorial/1-serialization.md index 03c7ad717..5f292211d 100644 --- a/docs/tutorial/1-serialization.md +++ b/docs/tutorial/1-serialization.md @@ -4,7 +4,7 @@ This tutorial will cover creating a simple pastebin code highlighting Web API. Along the way it will introduce the various components that make up REST framework, and give you a comprehensive understanding of how everything fits together. -The tutorial is fairly in-depth, so you should probably get a cookie and a cup of your favorite brew before getting started. +The tutorial is fairly in-depth, so you should probably get a cookie and a cup of your favorite brew before getting started. If you just want a quick overview, you should head over to the [quickstart] documentation instead. --- From 896477f6509fb56ec0a946560748885f6ca6fe8d Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Mon, 28 Jan 2013 07:54:03 +0000 Subject: [PATCH 13/30] Added @mktums for docs fix in #621. Thanks! --- docs/topics/credits.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/topics/credits.md b/docs/topics/credits.md index 7cffbede3..19a6397c2 100644 --- a/docs/topics/credits.md +++ b/docs/topics/credits.md @@ -96,6 +96,7 @@ The following people have helped make REST framework great. * Bruno Renié - [brutasse] * Kevin Stone - [kevinastone] * Guglielmo Celata - [guglielmo] +* Mike Tums - [mktums] Many thanks to everyone who's contributed to the project. @@ -227,3 +228,4 @@ You can also contact [@_tomchristie][twitter] directly on twitter. [brutasse]: https://github.com/brutasse [kevinastone]: https://github.com/kevinastone [guglielmo]: https://github.com/guglielmo +[mktums]: https://github.com/mktums From e682bfa54efc391df4d6bb7cf78a2089213b8d6b Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Mon, 28 Jan 2013 08:01:54 +0000 Subject: [PATCH 14/30] Drop unneccessary `source=` argument. --- docs/api-guide/relations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api-guide/relations.md b/docs/api-guide/relations.md index 351b5e09e..9f5a04b2d 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 From 3bcd38b7d0ddaa2c051ad230cb0d749f9737fd82 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Mon, 28 Jan 2013 09:10:23 +0000 Subject: [PATCH 15/30] Notes on upgrading and versioning. Fixes #620. --- docs/topics/release-notes.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/topics/release-notes.md b/docs/topics/release-notes.md index 0c3ebca04..84b30d85f 100644 --- a/docs/topics/release-notes.md +++ b/docs/topics/release-notes.md @@ -12,6 +12,16 @@ Medium version numbers (0.x.0) may include minor API changes. You should read t Major version numbers (x.0.0) are reserved for project milestones. No major point releases are currently planned. +## Upgrading + +To upgrade Django REST framework to the latest version, use pip: + + pip install -U djangorestframework + +You can determine your currently installed version using `pip freeze`: + + pip freeze | grep djangorestframework + --- ## 2.1.x series From 180c94dc44a9cc5b882364a58b0b12a8ab430c22 Mon Sep 17 00:00:00 2001 From: Michael Elovskikh Date: Mon, 28 Jan 2013 15:54:00 +0600 Subject: [PATCH 16/30] Undo changes in browsable-api.md and browser-enhancements.md --- docs/topics/browsable-api.md | 3 +-- docs/topics/browser-enhancements.md | 8 ++++---- 2 files changed, 5 insertions(+), 6 deletions(-) diff --git a/docs/topics/browsable-api.md b/docs/topics/browsable-api.md index 479987a19..9fe82e696 100644 --- a/docs/topics/browsable-api.md +++ b/docs/topics/browsable-api.md @@ -5,7 +5,7 @@ > — [Alfred North Whitehead][cite], An Introduction to Mathematics (1911) -API may stand for Application *Programming* Interface, but humans have to be able to read the APIs, too; someone has to do the programming. Django REST Framework supports generating human-friendly HTML output for each resource when the `HTML` format is requested. These pages allow for easy browsing of resources, as well as forms for submitting data to the resources using `POST`, `PUT`, `PATCH` and `DELETE`. +API may stand for Application *Programming* Interface, but humans have to be able to read the APIs, too; someone has to do the programming. Django REST Framework supports generating human-friendly HTML output for each resource when the `HTML` format is requested. These pages allow for easy browsing of resources, as well as forms for submitting data to the resources using `POST`, `PUT`, and `DELETE`. ## URLs @@ -79,7 +79,6 @@ The context that's available to the template: * `name` : The name of the resource * `post_form` : A form instance for use by the POST form (if allowed) * `put_form` : A form instance for use by the PUT form (if allowed) -* `patch_form` : A form instance for use by the PATCH form (if allowed) * `request` : The request object * `response` : The response object * `version` : The version of Django REST Framework diff --git a/docs/topics/browser-enhancements.md b/docs/topics/browser-enhancements.md index 3949f7a60..6a11f0fac 100644 --- a/docs/topics/browser-enhancements.md +++ b/docs/topics/browser-enhancements.md @@ -1,12 +1,12 @@ # Browser enhancements -> "There are two noncontroversial uses for overloaded POST. The first is to *simulate* HTTP's uniform interface for clients like web browsers that don't support PUT, PATCH or DELETE" +> "There are two noncontroversial uses for overloaded POST. The first is to *simulate* HTTP's uniform interface for clients like web browsers that don't support PUT or DELETE" > > — [RESTful Web Services][cite], Leonard Richardson & Sam Ruby. -## Browser based PUT, PATCH, DELETE, etc... +## Browser based PUT, DELETE, etc... -REST framework supports browser-based `PUT`, `PATCH`, `DELETE` and other methods, by +REST framework supports browser-based `PUT`, `DELETE` and other methods, by overloading `POST` requests using a hidden form field. Note that this is the same strategy as is used in [Ruby on Rails][rails]. @@ -51,7 +51,7 @@ the view. This is a more concise than using the `accept` override, but it also gives you less control. (For example you can't specify any media type parameters) -## Doesn't HTML5 support PUT, PATCH and DELETE forms? +## Doesn't HTML5 support PUT and DELETE forms? Nope. It was at one point intended to support `PUT` and `DELETE` forms, but was later [dropped from the spec][html5]. There remains From cb5cc70cbac7531693594a416a0397db61dda94c Mon Sep 17 00:00:00 2001 From: Michael Elovskikh Date: Mon, 28 Jan 2013 18:01:44 +0600 Subject: [PATCH 17/30] Login page styles fix. Closes #618. Made with :cookie: --- rest_framework/templates/rest_framework/login.html | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/rest_framework/templates/rest_framework/login.html b/rest_framework/templates/rest_framework/login.html index 6e2bd8d4d..e10ce20f3 100644 --- a/rest_framework/templates/rest_framework/login.html +++ b/rest_framework/templates/rest_framework/login.html @@ -25,14 +25,14 @@
      {% csrf_token %}
      -
      - +
      +
      -
      - +
      +
      From 661c8f9ad56a1f5f35e4a769ac44b668227b14e6 Mon Sep 17 00:00:00 2001 From: swistakm Date: Mon, 28 Jan 2013 13:05:52 +0100 Subject: [PATCH 18/30] fix mistake in docs --- docs/api-guide/authentication.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/api-guide/authentication.md b/docs/api-guide/authentication.md index da4947462..59afc2b9f 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 From 2f14d79f4aad89a2a1ebd1191d99bdada2274fe9 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Mon, 28 Jan 2013 11:43:41 +0000 Subject: [PATCH 19/30] Added @wronglink, for docs fixes in #592. Thanks! --- docs/topics/credits.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/topics/credits.md b/docs/topics/credits.md index 19a6397c2..930cc056b 100644 --- a/docs/topics/credits.md +++ b/docs/topics/credits.md @@ -97,6 +97,7 @@ The following people have helped make REST framework great. * Kevin Stone - [kevinastone] * Guglielmo Celata - [guglielmo] * Mike Tums - [mktums] +* Michael Elovskikh - [wronglink] Many thanks to everyone who's contributed to the project. @@ -229,3 +230,4 @@ You can also contact [@_tomchristie][twitter] directly on twitter. [kevinastone]: https://github.com/kevinastone [guglielmo]: https://github.com/guglielmo [mktums]: https://github.com/mktums +[wronglink]: https://github.com/wronglink From 94c4a54bf806aef7af6b5f8b5d996060f1daad0f Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Mon, 28 Jan 2013 12:23:18 +0000 Subject: [PATCH 20/30] Update release notes. --- docs/topics/release-notes.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/topics/release-notes.md b/docs/topics/release-notes.md index 84b30d85f..945d40189 100644 --- a/docs/topics/release-notes.md +++ b/docs/topics/release-notes.md @@ -26,6 +26,10 @@ You can determine your currently installed version using `pip freeze`: ## 2.1.x series +### Master + +* Fix styling on browsable API login. + ### 2.1.17 **Date**: 26th Jan 2013 From a3a06d11cc39da55d34f99e272bf092a2dcd4c5c Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Mon, 28 Jan 2013 12:56:42 +0000 Subject: [PATCH 21/30] Ensure model field validation is performed for ModelSerializers with a custom restore_object method. Fixes #623. --- rest_framework/serializers.py | 30 ++++++++++++++++++++++++------ rest_framework/tests/serializer.py | 27 +++++++++++++++++++++++++++ 2 files changed, 51 insertions(+), 6 deletions(-) diff --git a/rest_framework/serializers.py b/rest_framework/serializers.py index 6ecc7b458..0fed2c29c 100644 --- a/rest_framework/serializers.py +++ b/rest_framework/serializers.py @@ -513,6 +513,22 @@ class ModelSerializer(Serializer): exclusions.remove(field_name) return exclusions + def full_clean(self, instance): + """ + Perform Django's full_clean, and populate the `errors` dictionary + if any validation errors occur. + + Note that we don't perform this inside the `.restore_object()` method, + so that subclasses can override `.restore_object()`, and still get + the full_clean validation checking. + """ + try: + instance.full_clean(exclude=self.get_validation_exclusions()) + except ValidationError, err: + self._errors = err.message_dict + return None + return instance + def restore_object(self, attrs, instance=None): """ Restore the model instance. @@ -544,14 +560,16 @@ class ModelSerializer(Serializer): else: instance = self.opts.model(**attrs) - try: - instance.full_clean(exclude=self.get_validation_exclusions()) - except ValidationError, err: - self._errors = err.message_dict - return None - return instance + def from_native(self, data, files): + """ + Override the default method to also include model field validation. + """ + instance = super(ModelSerializer, self).from_native(data, files) + if instance: + return self.full_clean(instance) + def save(self): """ Save the deserialized object and return it. diff --git a/rest_framework/tests/serializer.py b/rest_framework/tests/serializer.py index b4428ca31..48b4f1ab9 100644 --- a/rest_framework/tests/serializer.py +++ b/rest_framework/tests/serializer.py @@ -54,6 +54,19 @@ class ActionItemSerializer(serializers.ModelSerializer): model = ActionItem +class ActionItemSerializerCustomRestore(serializers.ModelSerializer): + + class Meta: + model = ActionItem + + def restore_object(self, data, instance=None): + if instance is None: + return ActionItem(**data) + for key, val in data.items(): + setattr(instance, key, val) + return instance + + class PersonSerializer(serializers.ModelSerializer): info = serializers.Field(source='info') @@ -273,6 +286,20 @@ class ValidationTests(TestCase): self.assertEquals(serializer.is_valid(), False) self.assertEquals(serializer.errors, {'title': [u'Ensure this value has at most 200 characters (it has 201).']}) + def test_modelserializer_max_length_exceeded_with_custom_restore(self): + """ + When overriding ModelSerializer.restore_object, validation tests should still apply. + Regression test for #623. + + https://github.com/tomchristie/django-rest-framework/pull/623 + """ + data = { + 'title': 'x' * 201, + } + serializer = ActionItemSerializerCustomRestore(data=data) + self.assertEquals(serializer.is_valid(), False) + self.assertEquals(serializer.errors, {'title': [u'Ensure this value has at most 200 characters (it has 201).']}) + def test_default_modelfield_max_length_exceeded(self): data = { 'title': 'Testing "info" field...', From 141814585c72828f099a76c54bf2a5191833fc04 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Mon, 28 Jan 2013 12:58:22 +0000 Subject: [PATCH 22/30] Update release notes --- docs/topics/release-notes.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/topics/release-notes.md b/docs/topics/release-notes.md index 945d40189..a6de11889 100644 --- a/docs/topics/release-notes.md +++ b/docs/topics/release-notes.md @@ -28,7 +28,8 @@ You can determine your currently installed version using `pip freeze`: ### Master -* Fix styling on browsable API login. +* Bugfix: Fix styling on browsable API login. +* Bugfix: Ensure model field validation is still applied for ModelSerializer subclasses with an custom `.restore_object()` method. ### 2.1.17 From 85e6360792e1adbee1d457e25dc2d357c6d55adc Mon Sep 17 00:00:00 2001 From: Andrea de Marco <24erre@gmail.com> Date: Mon, 28 Jan 2013 22:08:40 +0100 Subject: [PATCH 23/30] Update rest_framework/serializers.py --- rest_framework/serializers.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rest_framework/serializers.py b/rest_framework/serializers.py index 0fed2c29c..4fb802a7c 100644 --- a/rest_framework/serializers.py +++ b/rest_framework/serializers.py @@ -469,7 +469,7 @@ class ModelSerializer(Serializer): kwargs['required'] = False kwargs['default'] = model_field.get_default() - if model_field.__class__ == models.TextField: + if issubclass(model_field.__class__, models.TextField): kwargs['widget'] = widgets.Textarea # TODO: TypedChoiceField? From 54096a19fc096c884c57e7a06340bf295a9098fb Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Mon, 28 Jan 2013 21:08:53 +0000 Subject: [PATCH 24/30] Added @swistakm, for docs fix #625. Thanks! --- docs/topics/credits.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/topics/credits.md b/docs/topics/credits.md index 930cc056b..7e0546c73 100644 --- a/docs/topics/credits.md +++ b/docs/topics/credits.md @@ -98,6 +98,7 @@ The following people have helped make REST framework great. * Guglielmo Celata - [guglielmo] * Mike Tums - [mktums] * Michael Elovskikh - [wronglink] +* Michał Jaworski - [swistakm] Many thanks to everyone who's contributed to the project. @@ -231,3 +232,4 @@ You can also contact [@_tomchristie][twitter] directly on twitter. [guglielmo]: https://github.com/guglielmo [mktums]: https://github.com/mktums [wronglink]: https://github.com/wronglink +[swistakm]: https://github.com/swistakm From 5f065153c31b586ca058deb8f6bd48303e3628e5 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Tue, 29 Jan 2013 09:10:37 +0000 Subject: [PATCH 25/30] Added @z4r. Thanks! For ensuring `django-jsonfield` compatibility, via #629. --- docs/topics/credits.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/topics/credits.md b/docs/topics/credits.md index 7e0546c73..2aa2c7151 100644 --- a/docs/topics/credits.md +++ b/docs/topics/credits.md @@ -99,6 +99,7 @@ The following people have helped make REST framework great. * Mike Tums - [mktums] * Michael Elovskikh - [wronglink] * Michał Jaworski - [swistakm] +* Andrea de Marco - [z4r] Many thanks to everyone who's contributed to the project. @@ -233,3 +234,4 @@ You can also contact [@_tomchristie][twitter] directly on twitter. [mktums]: https://github.com/mktums [wronglink]: https://github.com/wronglink [swistakm]: https://github.com/swistakm +[z4r]: https://github.com/z4r From 1929159db1b45ef28d1f7fdf0bea9d0867af13f3 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Tue, 29 Jan 2013 09:15:08 +0000 Subject: [PATCH 26/30] Docs tweaks. --- docs/api-guide/fields.md | 4 +++- docs/api-guide/serializers.md | 12 +++--------- 2 files changed, 6 insertions(+), 10 deletions(-) diff --git a/docs/api-guide/fields.md b/docs/api-guide/fields.md index e43282ce3..3f8a36e2a 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 d98a602f7..487502e9a 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__ --- From fceacd830fcd3b67425dafd5b0e6dcc5b285b6ca Mon Sep 17 00:00:00 2001 From: Fernando Rocha Date: Tue, 29 Jan 2013 18:46:05 -0300 Subject: [PATCH 27/30] Fix processing of ManyToManyField when it is empty Signed-off-by: Fernando Rocha --- rest_framework/relations.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rest_framework/relations.py b/rest_framework/relations.py index af63ceaaa..dc0a73e66 100644 --- a/rest_framework/relations.py +++ b/rest_framework/relations.py @@ -148,7 +148,7 @@ class ManyRelatedMixin(object): value = data.getlist(self.source or field_name) except: # Non-form data - value = data.get(self.source or field_name) + value = data.get(self.source or field_name, []) else: if value == ['']: value = [] From 41364b3be0536a606d9b41d3792c2e562b860360 Mon Sep 17 00:00:00 2001 From: Fernando Rocha Date: Wed, 30 Jan 2013 09:09:17 -0300 Subject: [PATCH 28/30] Added regretion test for issue #632 Signed-off-by: Fernando Rocha --- rest_framework/tests/relations.py | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/rest_framework/tests/relations.py b/rest_framework/tests/relations.py index 91daea8a6..edc85f9ea 100644 --- a/rest_framework/tests/relations.py +++ b/rest_framework/tests/relations.py @@ -31,3 +31,17 @@ class FieldTests(TestCase): field = serializers.SlugRelatedField(queryset=NullModel.objects.all(), slug_field='pk') self.assertRaises(serializers.ValidationError, field.from_native, '') self.assertRaises(serializers.ValidationError, field.from_native, []) + + +class TestManyRelateMixin(TestCase): + def test_missing_many_to_many_related_field(self): + ''' + Regression test for #632 + + https://github.com/tomchristie/django-rest-framework/pull/632 + ''' + field = serializers.ManyRelatedField(read_only=False) + + into = {} + field.field_from_native({}, None, 'field_name', into) + self.assertEqual(into['field_name'], []) From ce914b03ed602f76a6b75eb76417a8711b6a8b5e Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Wed, 30 Jan 2013 12:42:51 +0000 Subject: [PATCH 29/30] Updated release notes. --- docs/topics/release-notes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/topics/release-notes.md b/docs/topics/release-notes.md index a6de11889..70c915b76 100644 --- a/docs/topics/release-notes.md +++ b/docs/topics/release-notes.md @@ -29,6 +29,7 @@ You can determine your currently installed version using `pip freeze`: ### Master * Bugfix: Fix styling on browsable API login. +* Bugfix: Fix issue with deserializing empty to-many relations. * Bugfix: Ensure model field validation is still applied for ModelSerializer subclasses with an custom `.restore_object()` method. ### 2.1.17 From 8021bb5d5089955b171173e60dcc0968e13d29ea Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Wed, 30 Jan 2013 12:43:52 +0000 Subject: [PATCH 30/30] Added @fernandogrd for bugfix #632. Thanks! --- docs/topics/credits.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/topics/credits.md b/docs/topics/credits.md index 2aa2c7151..a67a81690 100644 --- a/docs/topics/credits.md +++ b/docs/topics/credits.md @@ -100,6 +100,7 @@ The following people have helped make REST framework great. * Michael Elovskikh - [wronglink] * Michał Jaworski - [swistakm] * Andrea de Marco - [z4r] +* Fernando Rocha - [fernandogrd] Many thanks to everyone who's contributed to the project. @@ -235,3 +236,4 @@ You can also contact [@_tomchristie][twitter] directly on twitter. [wronglink]: https://github.com/wronglink [swistakm]: https://github.com/swistakm [z4r]: https://github.com/z4r +[fernandogrd]: https://github.com/fernandogrd