From 679a50d09e4b0f035fec4e9554ea9aeb55944a1a Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Wed, 12 Sep 2012 13:12:00 +0100 Subject: [PATCH] Latest docs build --- api-guide/authentication.html | 1 + api-guide/content-negotiation.html | 1 + api-guide/exceptions.html | 7 ++++--- api-guide/format-suffixes.html | 1 + api-guide/generic-views.html | 1 + api-guide/parsers.html | 1 + api-guide/permissions.html | 13 +++++++++++-- api-guide/renderers.html | 1 + api-guide/requests.html | 1 + api-guide/responses.html | 1 + api-guide/reverse.html | 1 + api-guide/serializers.html | 1 + api-guide/settings.html | 1 + api-guide/status-codes.html | 1 + api-guide/throttling.html | 1 + api-guide/views.html | 1 + css/drf-styles.css | 7 +++++++ index.html | 1 + topics/contributing.html | 1 + topics/credits.html | 1 + topics/csrf.html | 1 + topics/formoverloading.html | 1 + tutorial/1-serialization.html | 1 + tutorial/2-requests-and-responses.html | 1 + tutorial/3-class-based-views.html | 1 + ...4-authentication-permissions-and-throttling.html | 1 + tutorial/5-relationships-and-hyperlinked-apis.html | 1 + tutorial/6-resource-orientated-projects.html | 1 + 28 files changed, 47 insertions(+), 5 deletions(-) diff --git a/api-guide/authentication.html b/api-guide/authentication.html index b87770129..5a001f13a 100644 --- a/api-guide/authentication.html +++ b/api-guide/authentication.html @@ -21,6 +21,7 @@
+ GitHub diff --git a/api-guide/content-negotiation.html b/api-guide/content-negotiation.html index 5048bd1db..5291f12c8 100644 --- a/api-guide/content-negotiation.html +++ b/api-guide/content-negotiation.html @@ -21,6 +21,7 @@
+ GitHub diff --git a/api-guide/exceptions.html b/api-guide/exceptions.html index 907abaf7a..b75545da3 100644 --- a/api-guide/exceptions.html +++ b/api-guide/exceptions.html @@ -21,6 +21,7 @@
+ GitHub @@ -112,15 +113,15 @@

— Doug Hellmann, Python Exception Handling Techniques

Exception handling in REST framework views

-

REST framework's views handle various exceptions, and deal with returning appropriate error responses for you.

+

REST framework's views handle various exceptions, and deal with returning appropriate error responses.

The handled exceptions are:

  • Subclasses of APIException raised inside REST framework.
  • Django's Http404 exception.
  • Django's PermissionDenied exception.
-

In each case, REST framework will return a response, rendering it to an appropriate content-type.

-

By default all error messages will include a key details in the body of the response, but other keys may also be included.

+

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.

+

By default all error responses will include a key details in the body of the response, but other keys may also be included.

For example, the following request:

DELETE http://api.example.com/foo/bar HTTP/1.1
 Accept: application/json
diff --git a/api-guide/format-suffixes.html b/api-guide/format-suffixes.html
index 52cd59936..7bfc8c5b1 100644
--- a/api-guide/format-suffixes.html
+++ b/api-guide/format-suffixes.html
@@ -21,6 +21,7 @@
     

       

         

+            GitHub
           
             
             
diff --git a/api-guide/generic-views.html b/api-guide/generic-views.html
index 21835f026..2f2da04bd 100644
--- a/api-guide/generic-views.html
+++ b/api-guide/generic-views.html
@@ -21,6 +21,7 @@
     

       

         

+            GitHub
           
             
             
diff --git a/api-guide/parsers.html b/api-guide/parsers.html
index 72396b0ae..d07c9cf31 100644
--- a/api-guide/parsers.html
+++ b/api-guide/parsers.html
@@ -21,6 +21,7 @@
     

       

         

+            GitHub
           
             
             
diff --git a/api-guide/permissions.html b/api-guide/permissions.html
index bd33c122f..28f691816 100644
--- a/api-guide/permissions.html
+++ b/api-guide/permissions.html
@@ -21,6 +21,7 @@
     

       

         

+            GitHub
           
             
             
@@ -115,7 +116,7 @@
 
Together with authentication and throttling, permissions determine wheter a request should be granted or denied access.

 
Permission checks are always run at the very start of the view, before any other code is allowed to proceed.  Permission checks will typically use the authentication information in the request.user and request.auth properties to determine if the incoming request should be permitted.

 
How permissions are determined

-
Permissions in REST framework are always defined as a list of permission classes.  Before running the main body of the view, each permission in the list is checked.

+
Permissions in REST framework are always defined as a list of permission classes.  Before running the main body of the view each permission in the list is checked.

 
If any permission check fails an exceptions.PermissionDenied exception will be raised, and the main body of the view will not run.

 
Object level permissions

 
REST framework permissions also support object-level permissioning.  Object level permissions are used to determine if a user should be allowed to act on a particular object, which will typically be a model instance.

@@ -157,7 +158,15 @@ def example_view(request, format=None):
 
The IsAuthenticatedOrReadOnly will allow authenticated users to perform any request.  Requests for unauthorised users will only be permitted if the request method is one of the "safe" methods; GET, HEAD or OPTIONS.

 
This permission is suitable if you want to your API to allow read permissions to anonymous users, and only allow write permissions to authenticated users.

 
DjangoModelPermissions

-
This permission class ties into Django's standard django.contrib.auth model permissions.  When applied to a view that has a .model property, permission will only be granted if the user

+
This permission class ties into Django's standard django.contrib.auth model permissions.  When applied to a view that has a .model property, authorization will only be granted if the user has the relevant model permissions assigned.

+
    
+
  • POST requests require the user to have the add permission on the model.
    • 
+
  • PUT and PATCH requests require the user to have the change permission on the model.
    • 
+
  • DELETE requests require the user to have the delete permission on the model.
    • 
+

+
The default behaviour can also be overridden to support custom model permissions.  For example, you might want to include a view model permission for GET requests.

+
To use custom model permissions, override DjangoModelPermissions and set the .perms_map property.  Refer to the source code for details.

+
The DjangoModelPermissions class also supports object-level permissions.  Third-party authorization backends such as django-guardian should work just fine with DjangoModelPermissions without any custom configuration required.

 
Custom permissions

 
To implement a custom permission, override BasePermission and implement the .check_permission(self, request, obj=None) method.

 
The method should return True if the request should be granted access, and False otherwise.

diff --git a/api-guide/renderers.html b/api-guide/renderers.html
index 1d6112c16..570d4afff 100644
--- a/api-guide/renderers.html
+++ b/api-guide/renderers.html
@@ -21,6 +21,7 @@
     

       

         

+            GitHub
           
             
             
diff --git a/api-guide/requests.html b/api-guide/requests.html
index 596100f7c..e45f38a52 100644
--- a/api-guide/requests.html
+++ b/api-guide/requests.html
@@ -21,6 +21,7 @@
     

       

         

+            GitHub
           
             
             
diff --git a/api-guide/responses.html b/api-guide/responses.html
index c4379c50b..8739fd728 100644
--- a/api-guide/responses.html
+++ b/api-guide/responses.html
@@ -21,6 +21,7 @@
     

       

         

+            GitHub
           
             
             
diff --git a/api-guide/reverse.html b/api-guide/reverse.html
index 7be8aa95a..bf31596b9 100644
--- a/api-guide/reverse.html
+++ b/api-guide/reverse.html
@@ -21,6 +21,7 @@
     

       

         

+            GitHub
           
             
             
diff --git a/api-guide/serializers.html b/api-guide/serializers.html
index 976855eb4..e652aea07 100644
--- a/api-guide/serializers.html
+++ b/api-guide/serializers.html
@@ -21,6 +21,7 @@
     

       

         

+            GitHub
           
             
             
diff --git a/api-guide/settings.html b/api-guide/settings.html
index af51f90c4..42c5559d7 100644
--- a/api-guide/settings.html
+++ b/api-guide/settings.html
@@ -21,6 +21,7 @@
     

       

         

+            GitHub
           
             
             
diff --git a/api-guide/status-codes.html b/api-guide/status-codes.html
index 73fd184fb..4bae10dfc 100644
--- a/api-guide/status-codes.html
+++ b/api-guide/status-codes.html
@@ -21,6 +21,7 @@
     

       

         

+            GitHub
           
             
             
diff --git a/api-guide/throttling.html b/api-guide/throttling.html
index 3e150d269..087bea05b 100644
--- a/api-guide/throttling.html
+++ b/api-guide/throttling.html
@@ -21,6 +21,7 @@
     

       

         

+            GitHub
           
             
             
diff --git a/api-guide/views.html b/api-guide/views.html
index 2818c8d5e..66d23baf6 100644
--- a/api-guide/views.html
+++ b/api-guide/views.html
@@ -21,6 +21,7 @@
     

       

         

+            GitHub
           
             
             
diff --git a/css/drf-styles.css b/css/drf-styles.css
index a5f0b97a2..7ad9d717f 100644
--- a/css/drf-styles.css
+++ b/css/drf-styles.css
@@ -22,6 +22,13 @@ pre {
     display: block;
 }
 
+/* Header link to GitHub */
+.repo-link {
+    float: right;
+    margin-right: 10px;
+    margin-top: 7px;
+}
+
 /* GitHub 'Star' badge */
 body.index #main-content iframe {
     float: right;
diff --git a/index.html b/index.html
index 8ee99a975..2f1abd947 100644
--- a/index.html
+++ b/index.html
@@ -21,6 +21,7 @@
     

       

         

+            GitHub
           
             
             
diff --git a/topics/contributing.html b/topics/contributing.html
index bd8fbc26f..ea58c5e76 100644
--- a/topics/contributing.html
+++ b/topics/contributing.html
@@ -21,6 +21,7 @@
     

       

         

+            GitHub
           
             
             
diff --git a/topics/credits.html b/topics/credits.html
index 1c965399d..750f52c9e 100644
--- a/topics/credits.html
+++ b/topics/credits.html
@@ -21,6 +21,7 @@
     

       

         

+            GitHub
           
             
             
diff --git a/topics/csrf.html b/topics/csrf.html
index 487764403..1f0002653 100644
--- a/topics/csrf.html
+++ b/topics/csrf.html
@@ -21,6 +21,7 @@
     

       

         

+            GitHub
           
             
             
diff --git a/topics/formoverloading.html b/topics/formoverloading.html
index 005343c8a..a2e96bf6b 100644
--- a/topics/formoverloading.html
+++ b/topics/formoverloading.html
@@ -21,6 +21,7 @@
     

       

         

+            GitHub
           
             
             
diff --git a/tutorial/1-serialization.html b/tutorial/1-serialization.html
index 7e6231609..5b4b9ffdc 100644
--- a/tutorial/1-serialization.html
+++ b/tutorial/1-serialization.html
@@ -21,6 +21,7 @@
     

       

         

+            GitHub
           
             
             
diff --git a/tutorial/2-requests-and-responses.html b/tutorial/2-requests-and-responses.html
index 9a5b0d2f5..4a6a2af4f 100644
--- a/tutorial/2-requests-and-responses.html
+++ b/tutorial/2-requests-and-responses.html
@@ -21,6 +21,7 @@
     

       

         

+            GitHub
           
             
             
diff --git a/tutorial/3-class-based-views.html b/tutorial/3-class-based-views.html
index 620f3f536..f4392da81 100644
--- a/tutorial/3-class-based-views.html
+++ b/tutorial/3-class-based-views.html
@@ -21,6 +21,7 @@
     

       

         

+            GitHub
           
             
             
diff --git a/tutorial/4-authentication-permissions-and-throttling.html b/tutorial/4-authentication-permissions-and-throttling.html
index 3e4206335..d1e78b1ba 100644
--- a/tutorial/4-authentication-permissions-and-throttling.html
+++ b/tutorial/4-authentication-permissions-and-throttling.html
@@ -21,6 +21,7 @@
     

       

         

+            GitHub
           
             
             
diff --git a/tutorial/5-relationships-and-hyperlinked-apis.html b/tutorial/5-relationships-and-hyperlinked-apis.html
index 18c580a7e..9c0693351 100644
--- a/tutorial/5-relationships-and-hyperlinked-apis.html
+++ b/tutorial/5-relationships-and-hyperlinked-apis.html
@@ -21,6 +21,7 @@
     

       

         

+            GitHub
           
             
             
diff --git a/tutorial/6-resource-orientated-projects.html b/tutorial/6-resource-orientated-projects.html
index a6f543998..f0d80c642 100644
--- a/tutorial/6-resource-orientated-projects.html
+++ b/tutorial/6-resource-orientated-projects.html
@@ -21,6 +21,7 @@
     

       

         

+            GitHub