docs, docs, docs, docs, docs, docs, docs

docs/api-guide/content-negotiation.md

@@ -8,8 +8,59 @@
 
 [cite]: http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html
 
-**TODO**: Describe content negotiation style used by REST framework.
+Content negotiation is the process of selecting one of multiple possible representations to return to a client, based on client or server preferences.
 
-## Custom content negotiation
+## Determining the accepted renderer
 
-It's unlikley that you'll want to provide a custom content negotiation scheme for REST framework, but you can do so if needed.  To implement a custom content negotiation scheme, override `BaseContentNegotiation`, and implement the `.select_parser(request, parsers)` and `.select_renderer(request, renderers, format_suffix)`
+REST framework uses a simple style of content negotition to determine which media type should be returned to a client, based on the available renderers, the priorities of each of those renderers, and the client's `Accept:` header.  The style used is partly client-driven, and partly server-driven.
+
+1. More specific media types are given preference to less specific media types.
+2. If multiple media types have the same specificity, then preference is given to based on the ordering of the renderers configured for the given view.
+
+For example, given the following `Accept` header:
+
+    application/json; indent=4, application/json, application/yaml, text/html, */*
+
+The priorities for each of the given media types would be:
+
+* `application/json; indent=4`
+* `application/json`, `application/yaml` and `text/html`
+* `*/*`
+
+If the requested view was only configured with renderers for `YAML` and `HTML`, then REST framework would select whichever renderer was listed first in the `renderer_classes` list or `DEFAULT_RENDERER_CLASSES` setting.
+
+For more information on the `HTTP Accept` header, see [RFC 2616][accept-header] 
+
+---
+
+**Note**: "q" values are not taken into account by REST framework when determining preference.  The use of "q" values negatively impacts caching, and in the author's opinion they are an unnecessary and overcomplicated approach to content negotiation.
+
+This is a valid approach as the HTTP spec deliberately underspecifies how a server should weight server-based preferences against client-based preferences.
+
+---
+
+# Custom content negotiation
+
+It's unlikley that you'll want to provide a custom content negotiation scheme for REST framework, but you can do so if needed.  To implement a custom content negotiation scheme override `BaseContentNegotiation`.
+
+REST framework's content negotiation classes handle selection of both the approprate parser for the requesr, and the appropriate renderer for the response,  so you should implement both the `.select_parser(request, parsers)` and `.select_renderer(request, renderers, format_suffix)` methods.
+
+## Example
+
+The following is a custom content negotiation class which ignores the client
+request when selecting the appropriate parser or renderer.
+
+    class IgnoreClientContentNegotiation(BaseContentNegotiation):
+        def select_parser(self, request, parsers):
+            """
+            Select the first parser in the `.parser_classes` list.
+            """
+            return parsers[0]
+        
+        def select_renderer(self, request, renderers, format_suffix):
+            """
+            Select the first renderer in the `.renderer_classes` list.
+            """
+            return renderers[0]
+
+[accept-header]: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html

docs/api-guide/format-suffixes.md

@@ -7,5 +7,55 @@ used all the time.
 >
 > — Roy Fielding, [REST discuss mailing list][cite]
 
-[cite]: http://tech.groups.yahoo.com/group/rest-discuss/message/5857
+A common pattern for Web APIs is to use filename extensions on URLs to provide an endpoint for a given media type.  For example, 'http://example.com/api/users.json' to serve a JSON representation. 
 
+Adding format-suffix patterns to each individual entry in the URLconf for your API is error-prone and non-DRY, so REST framework provides a shortcut to adding these patterns to your URLConf.
+
+## format_suffix_patterns
+
+**Signature**: format_suffix_patterns(urlpatterns, suffix_required=False, allowed=None)
+
+Returns a URL pattern list which includes format suffix patterns appended to each of the URL patterns provided.
+
+Arguments:
+
+* **urlpatterns**: Required.  A URL pattern list.
+* **suffix_required**:  Optional.  A boolean indicating if suffixes in the URLs should be optional or mandatory.  Defaults to `False`, meaning that suffixes are optional by default.
+* **allowed**:  Optional.  A list or tuple of valid format suffixes.  If not provided, a wildcard format suffix pattern will be used. 
+
+Example:
+
+    from rest_framework.urlpatterns import format_suffix_patterns
+    
+    urlpatterns = patterns('blog.views',
+        url(r'^/$', 'api_root'),
+        url(r'^comment/$', 'comment_root'),
+        url(r'^comment/(?P<pk>[0-9]+)/$', 'comment_instance')
+    )
+    
+    urlpatterns = format_suffix_patterns(urlpatterns, allowed=['json', 'html'])
+
+When using `format_suffix_patterns`, you must make sure to add the `'format'` keyword argument to the corresponding views.  For example.
+
+    @api_view(('GET',))
+    def api_root(request, format=None):
+        # do stuff...
+
+The name of the kwarg used may be modified by using the `FORMAT_SUFFIX_KWARG` setting.
+
+Also note that `format_suffix_patterns` does not support descending into `include` URL patterns.
+
+---
+        
+## Accept headers vs. format suffixes
+
+There seems to be a view among some of the Web community that filename extensions are not a RESTful pattern, and that `HTTP Accept` headers should always be used instead.  
+
+It is actually a misconception.  For example, take the following quote from Roy Fielding discussing the relative merits of query parameter media-type indicators vs. file extension media-type indicators: 
+
+&ldquo;That's why I always prefer extensions. Neither choice has anything to do with REST.&rdquo; &mdash; Roy Fielding, [REST discuss mailing list][cite2]
+
+The quote does not mention Accept headers, but it does make it clear that format suffixes should be considered an acceptable pattern.
+
+[cite]: http://tech.groups.yahoo.com/group/rest-discuss/message/5857
+[cite2]: http://tech.groups.yahoo.com/group/rest-discuss/message/14844

docs/api-guide/pagination.md

@@ -100,12 +100,16 @@ You can also set the pagination style on a per-view basis, using the `ListAPIVie
 
 For more complex requirements such as serialization that differs depending on the requested media type you can override the `.get_paginate_by()` and `.get_pagination_serializer_class()` methods.
 
-## Custom pagination serializers
+---
+
+# Custom pagination serializers
 
 To create a custom pagination serializer class you should override `pagination.BasePaginationSerializer` and set the fields that you want the serializer to return.
 
 You can also override the name used for the object list field, by setting the `results_field` attribute, which defaults to `'results'`.
 
+## Example
+
 For example, to nest a pair of links labelled 'prev' and 'next', and set the name for the results field to 'objects', you might use something like this.
 
     class LinksSerializer(serializers.Serializer):

rest_framework/urlpatterns.py

@@ -2,26 +2,23 @@ from django.conf.urls.defaults import url
 from rest_framework.settings import api_settings
 
 
-def format_suffix_patterns(urlpatterns, suffix_required=False,
-                           suffix_kwarg=None, allowed=None):
+def format_suffix_patterns(urlpatterns, suffix_required=False, allowed=None):
     """
     Supplement existing urlpatterns with corrosponding patterns that also
     include a '.format' suffix.  Retains urlpattern ordering.
 
+    urlpatterns:
+        A list of URL patterns.
+
     suffix_required:
         If `True`, only suffixed URLs will be generated, and non-suffixed
         URLs will not be used.  Defaults to `False`.
 
-    suffix_kwarg:
-        The name of the kwarg that will be passed to the view.
-        Defaults to 'format'.
-
     allowed:
         An optional tuple/list of allowed suffixes.  eg ['json', 'api']
         Defaults to `None`, which allows any suffix.
-
     """
-    suffix_kwarg = suffix_kwarg or api_settings.FORMAT_SUFFIX_KWARG
+    suffix_kwarg = api_settings.FORMAT_SUFFIX_KWARG
     if allowed:
         if len(allowed) == 1:
             allowed_pattern = allowed[0]