Ticket #15906: patch_15906.diff

docs/ref/class-based-views.txt

@@ -867 +867 @@
         delegated to :meth:`~View.get()`, a ``POST`` to :meth:`~View.post()`,
         and so on.
 
+        By default, a ``HEAD`` request will be delegated to :meth:`~View.get()`.
+        If you need to handle ``HEAD`` requests in a different way than ``GET``,
+        you can override the :meth:`~View.head()` method.
+        See :ref:`supporting-other-http-methods` for an example.
+
         The default implementation also sets ``request``, ``args`` and
         ``kwargs`` as instance variables, so any method on the view can know
         the full details of the request that was made to invoke the view.

docs/topics/class-based-views.txt

@@ -554 +554 @@
 :class:`JSONResponseMixin` and
 :class:`~django.views.generic.detail.SingleObjectTemplateResponseMixin`.
 
+.. _supporting-other-http-methods:
+
+Supporting other HTTP methods
+-----------------------------
+
+Suppose somebody wants to access our book library over HTTP using the views
+as an API. The API client would connect every now and then and download book
+data for the books published since last visit. But if no new books appeared
+since then, it is a waste of CPU time and bandwidth to fetch the books from
+database, render a full response and send it to the client. It might be
+preferable to ask the API when the most recent book was published.
+
+We define the URL to book list in the URLconf::
+
+    from django.conf.urls import patterns
+    from books.views import BookListView
+
+    urlpatterns = patterns('',
+        (r'^books/$', BookListView.as_view()),
+    )
+
+And the view::
+
+    from django.http import HttpResponse
+    from django.views.generic import ListView
+    from books.models import Book
+
+    class BookListView(ListView):
+
+        model = Book
+
+        def head(self, *args, **kwargs):
+            last_book = self.get_queryset().latest('publication_date')
+            response = HttpResponse('')
+            # RFC 1123 date format
+            response['Last-Modified'] = last_book.publication_date.strftime('%a, %d %b %Y %H:%M:%S GMT')
+            return response
+
+If the view is accessed from a ``GET`` request, a plain-and-simple object
+list is returned in the response (using ``book_list.html`` template). But if
+the client issues a ``HEAD`` request, the response has an empty body and
+the ``Last-Modified`` header indicates when the most recent book was published.
+Based on this information, the client may or may not download the full object
+list.
+
 Decorating class-based views
 ============================