Issue #1707: Add documentation to api-docs.viewsets notifying users

that they should use the get_queryset() method when overriding a
ModelViewSet method, such as list(). Otherwise, since queryset is
a static property, the value will be cached for every instance of
that ViewSet.

1 files changed, 16 insertions, 1 deletions

diff --git a/docs/api-guide/viewsets.md b/docs/api-guide/viewsets.md
index 23b16575..774e11b7 100644
--- a/docs/api-guide/viewsets.md
+++ b/docs/api-guide/viewsets.md
@@ -70,6 +70,21 @@ There are two main advantages of using a `ViewSet` class over using a `View` cla
 
 Both of these come with a trade-off.  Using regular views and URL confs is more explicit and gives you more control.  ViewSets are helpful if you want to get up and running quickly, or when you have a large API and you want to enforce a consistent URL configuration throughout.
 
+## Overriding ModelViewSet Methods
+
+Overriding the ModelViewSet is the same as overriding anything else, except you will need to remember to clone `self.queryset` before you use it, which you can do by using the built-in `get_queryset` method. For example:
+
+    class UserViewSet(viewsets.ModelViewSet):
+        """
+        A viewset for viewing and editing user instances.
+        """
+        queryset = User.objects.all()
+
+        def list(self, request):
+            queryset = self.get_queryset()
+            serializer = UserSerializer(queryset, many=True)
+            return Response(serializer.data)
+
 ## Marking extra methods for routing
 
 The default routers included with REST framework will provide routes for a standard set of create/retrieve/update/destroy style operations, as shown below:
@@ -142,7 +157,7 @@ The `@action` decorator will route `POST` requests by default, but may also acce
         @action(methods=['POST', 'DELETE'])
         def unset_password(self, request, pk=None):
            ...
-           
+
 The two new actions will then be available at the urls `^users/{pk}/set_password/$` and `^users/{pk}/unset_password/$`