4 files changed, 46 insertions, 1 deletions
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
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.
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
diff --git a/docs/api-guide/throttling.md b/docs/api-guide/throttling.md
index b03bc9e0..923593bc 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 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):
+            return random.randint(1, 10) == 1
+
 [permissions]: permissions.md