diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/api-guide/permissions.md | 17 | ||||
| -rw-r--r-- | docs/index.md | 8 | ||||
| -rw-r--r-- | docs/template.html | 6 | ||||
| -rw-r--r-- | docs/topics/browser-enhancements.md | 16 | ||||
| -rw-r--r-- | docs/topics/credits.md | 2 | ||||
| -rw-r--r-- | docs/topics/release-notes.md | 8 |
6 files changed, 50 insertions, 7 deletions
diff --git a/docs/api-guide/permissions.md b/docs/api-guide/permissions.md index 719ac1ef..4772c5e0 100644 --- a/docs/api-guide/permissions.md +++ b/docs/api-guide/permissions.md @@ -105,6 +105,21 @@ The default behaviour can also be overridden to support custom model permissions To use custom model permissions, override `DjangoModelPermissions` and set the `.perms_map` property. Refer to the source code for details. +## TokenHasReadWriteScope + +This permission class is intended for use with either of the `OAuthAuthentication` and `OAuth2Authentication` classes, and ties into the scoping that their backends provide. + +Requests with a safe methods of `GET`, `OPTIONS` or `HEAD` will be allowed if the authenticated token has read permission. + +Requests for `POST`, `PUT`, `PATCH` and `DELETE` will be allowed if the authenticated token has write permission. + +This permission class relies on the implementations of the [django-oauth-plus][django-oauth-plus] and [django-oauth2-provider][django-oauth2-provider] libraries, which both provide limited support for controlling the scope of access tokens: + +* `django-oauth-plus`: Tokens are associated with a `Resource` class which has a `name`, `url` and `is_readonly` properties. +* `django-oauth2-provider`: Tokens are associated with a bitwise `scope` attribute, that defaults to providing bitwise values for `read` and/or `write`. + +If you require more advanced scoping for your API, such as restricting tokens to accessing a subset of functionality of your API then you will need to provide a custom permission class. See the source of the `django-oauth-plus` or `django-oauth2-provider` package for more details on scoping token access. + --- # Custom permissions @@ -173,5 +188,7 @@ Also note that the generic views will only check the object-level permissions fo [throttling]: throttling.md [contribauth]: https://docs.djangoproject.com/en/1.0/topics/auth/#permissions [guardian]: https://github.com/lukaszb/django-guardian +[django-oauth-plus]: http://code.larlet.fr/django-oauth-plus +[django-oauth2-provider]: https://github.com/caffeinehit/django-oauth2-provider [2.2-announcement]: ../topics/2.2-announcement.md [filtering]: filtering.md diff --git a/docs/index.md b/docs/index.md index 8e5097b3..5357536d 100644 --- a/docs/index.md +++ b/docs/index.md @@ -9,11 +9,11 @@ # Django REST framework -**A toolkit for building well-connected, self-describing Web APIs.** +**Web APIs for Django, made easy.** -Django REST framework is a lightweight library that makes it easy to build Web APIs. It is designed as a modular and easy to customize architecture, based on Django's class based views. +Django REST framework is a flexible, powerful library that makes it incredibly easy to build Web APIs. It is designed as a modular and easy to customize architecture, based on Django's class based views. -Web APIs built using REST framework are fully self-describing and web browseable - a huge useability win for your developers. It also supports a wide range of media types, authentication and permission policies out of the box. +APIs built using REST framework are fully self-describing and web browseable - a huge useability win for your developers. It also supports a wide range of media types, authentication and permission policies out of the box. If you are considering using REST framework for your API, we recommend reading the [REST framework 2 announcement][rest-framework-2-announcement] which gives a good overview of the framework and it's capabilities. @@ -75,7 +75,7 @@ Note that the URL path can be whatever you want, but you must include `'rest_fra ## Quickstart -Can't wait to get started? The [quickstart guide][quickstart] is the fastest way to get up and running with REST framework. +Can't wait to get started? The [quickstart guide][quickstart] is the fastest way to get up and running, and building APIs with REST framework. ## Tutorial diff --git a/docs/template.html b/docs/template.html index e0f88daf..3e0f29aa 100644 --- a/docs/template.html +++ b/docs/template.html @@ -2,11 +2,11 @@ <html lang="en"> <head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> <meta charset="utf-8"> - <title>Django REST framework</title> + <title>{{ title }}</title> <link href="{{ base_url }}/img/favicon.ico" rel="icon" type="image/x-icon"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> - <meta name="description" content=""> - <meta name="author" content=""> + <meta name="description" content="{{ description }}"> + <meta name="author" content="Tom Christie"> <!-- Le styles --> <link href="{{ base_url }}/css/prettify.css" rel="stylesheet"> diff --git a/docs/topics/browser-enhancements.md b/docs/topics/browser-enhancements.md index 6a11f0fa..ce07fe95 100644 --- a/docs/topics/browser-enhancements.md +++ b/docs/topics/browser-enhancements.md @@ -19,6 +19,21 @@ For example, given the following form: `request.method` would return `"DELETE"`. +## HTTP header based method overriding + +REST framework also supports method overriding via the semi-standard `X-HTTP-Method-Override` header. This can be useful if you are working with non-form content such as JSON and are working with an older web server and/or hosting provider that doesn't recognise particular HTTP methods such as `PATCH`. For example [Amazon Web Services ELB][aws_elb]. + +To use it, make a `POST` request, setting the `X-HTTP-Method-Override` header. + +For example, making a `PATCH` request via `POST` in jQuery: + + $.ajax({ + url: '/myresource/', + method: 'POST', + headers: {'X-HTTP-Method-Override': 'PATCH'}, + ... + }); + ## Browser based submission of non-form content Browser-based submission of content types other than form are supported by @@ -62,3 +77,4 @@ as well as how to support content types other than form-encoded data. [rails]: http://guides.rubyonrails.org/form_helpers.html#how-do-forms-with-put-or-delete-methods-work [html5]: http://www.w3.org/TR/html5-diff/#changes-2010-06-24 [put_delete]: http://amundsen.com/examples/put-delete-forms/ +[aws_elb]: https://forums.aws.amazon.com/thread.jspa?messageID=400724 diff --git a/docs/topics/credits.md b/docs/topics/credits.md index b0f0cfa2..b533daa9 100644 --- a/docs/topics/credits.md +++ b/docs/topics/credits.md @@ -111,6 +111,7 @@ The following people have helped make REST framework great. * Ian Dash - [bitmonkey] * Bouke Haarsma - [bouke] * Pierre Dulac - [dulaccc] +* Dave Kuhn - [kuhnza] Many thanks to everyone who's contributed to the project. @@ -256,3 +257,4 @@ You can also contact [@_tomchristie][twitter] directly on twitter. [bitmonkey]: https://github.com/bitmonkey [bouke]: https://github.com/bouke [dulaccc]: https://github.com/dulaccc +[kuhnza]: https://github.com/kuhnza diff --git a/docs/topics/release-notes.md b/docs/topics/release-notes.md index ac201e20..c45fff88 100644 --- a/docs/topics/release-notes.md +++ b/docs/topics/release-notes.md @@ -42,11 +42,19 @@ You can determine your currently installed version using `pip freeze`: ### Master +* `Serializer.save()` now supports arbitrary keyword args which are passed through to the object `.save()` method. Mixins use `force_insert` and `force_update` where appropriate, resulting in one less database query. + +### 2.2.4 + +**Date**: 13th March 2013 + * OAuth 2 support. * OAuth 1.0a support. +* Support X-HTTP-Method-Override header. * Filtering backends are now applied to the querysets for object lookups as well as lists. (Eg you can use a filtering backend to control which objects should 404) * Deal with error data nicely when deserializing lists of objects. * Extra override hook to configure `DjangoModelPermissions` for unauthenticated users. +* Bugfix: Fix regression which caused extra database query on paginated list views. * Bugfix: Fix pk relationship bug for some types of 1-to-1 relations. * Bugfix: Workaround for Django bug causing case where `Authtoken` could be registered for cascade delete from `User` even if not installed. |