Merge pull request #1 from tomchristie/master

Merge in from upstream

.gitignore

@@ -3,18 +3,14 @@
 *~
 .*
 
-html/
-htmlcov/
-coverage/
-build/
-dist/
-*.egg-info/
+/site/
+/htmlcov/
+/coverage/
+/build/
+/dist/
+/*.egg-info/
+/env/
 MANIFEST
 
-bin/
-include/
-lib/
-local/
-
 !.gitignore
 !.travis.yml

.travis.yml

 language: python
 
-python:
-  - "2.6"
-  - "2.7"
-  - "3.2"
-  - "3.3"
+sudo: false
 
 env:
-  - DJANGO="https://www.djangoproject.com/download/1.6a1/tarball/"
-  - DJANGO="django==1.5.1 --use-mirrors"
-  - DJANGO="django==1.4.5 --use-mirrors"
-  - DJANGO="django==1.3.7 --use-mirrors"
+    - TOX_ENV=py27-flake8
+    - TOX_ENV=py27-docs
+    - TOX_ENV=py34-django17
+    - TOX_ENV=py33-django17
+    - TOX_ENV=py32-django17
+    - TOX_ENV=py27-django17
+    - TOX_ENV=py34-django16
+    - TOX_ENV=py33-django16
+    - TOX_ENV=py32-django16
+    - TOX_ENV=py27-django16
+    - TOX_ENV=py26-django16
+    - TOX_ENV=py34-django15
+    - TOX_ENV=py33-django15
+    - TOX_ENV=py32-django15
+    - TOX_ENV=py27-django15
+    - TOX_ENV=py26-django15
+    - TOX_ENV=py27-django14
+    - TOX_ENV=py26-django14
+    - TOX_ENV=py34-django18beta
+    - TOX_ENV=py33-django18beta
+    - TOX_ENV=py32-django18beta
+    - TOX_ENV=py27-django18beta
 
 install:
-  - pip install $DJANGO
-  - pip install defusedxml==0.3
-  - "if [[ ${TRAVIS_PYTHON_VERSION::1} != '3' ]]; then pip install oauth2==1.5.211 --use-mirrors; fi"
-  - "if [[ ${TRAVIS_PYTHON_VERSION::1} != '3' ]]; then pip install django-oauth-plus==2.0 --use-mirrors; fi"
-  - "if [[ ${TRAVIS_PYTHON_VERSION::1} != '3' ]]; then pip install django-oauth2-provider==0.2.4 --use-mirrors; fi"
-  - "if [[ ${DJANGO::11} == 'django==1.3' ]]; then pip install django-filter==0.5.4 --use-mirrors; fi"
-  - "if [[ ${DJANGO::11} != 'django==1.3' ]]; then pip install django-filter==0.6 --use-mirrors; fi"
-  - export PYTHONPATH=.
+  - pip install tox
 
 script:
-  - python rest_framework/runtests/runtests.py
-
-matrix:
-  exclude:
-    - python: "3.2"
-      env: DJANGO="django==1.4.5 --use-mirrors"
-    - python: "3.2"
-      env: DJANGO="django==1.3.7 --use-mirrors"
-    - python: "3.3"
-      env: DJANGO="django==1.4.5 --use-mirrors"
-    - python: "3.3"
-      env: DJANGO="django==1.3.7 --use-mirrors"
-
+    - tox -e $TOX_ENV

.tx/config

+[main]
+host = https://www.transifex.com
+
+[django-rest-framework.djangopo]
+file_filter = rest_framework/locale/<lang>/LC_MESSAGES/django.po
+source_file = rest_framework/locale/en_US/LC_MESSAGES/django.po
+source_lang = en_US
+type = PO
+

MANIFEST.in

-recursive-include rest_framework/static *.js *.css *.png
+recursive-include rest_framework/static *.js *.css *.png *.eot *.svg *.ttf *.woff
 recursive-include rest_framework/templates *.html
+recursive-exclude * __pycache__
+recursive-exclude * *.py[co]

docs/CNAME

+www.django-rest-framework.org

docs/api-guide/content-negotiation.md

-<a class="github" href="negotiation.py"></a>
+source: negotiation.py
 
 # Content negotiation
 
@@ -29,7 +29,7 @@ The priorities for each of the given media types would be:
 
 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] 
+For more information on the `HTTP Accept` header, see [RFC 2616][accept-header]
 
 ---
 
@@ -54,13 +54,15 @@ The `select_renderer()` method should return a two-tuple of (renderer instance,
 The following is a custom content negotiation class which ignores the client
 request when selecting the appropriate parser or renderer.
 
+    from rest_framework.negotiation import BaseContentNegotiation
+
     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.
@@ -77,6 +79,10 @@ The default content negotiation class may be set globally, using the `DEFAULT_CO
 
 You can also set the content negotiation used for an individual view, or viewset, using the `APIView` class based views.
 
+	from myapp.negotiation import IgnoreClientContentNegotiation
+    from rest_framework.response import Response
+    from rest_framework.views import APIView
+
     class NoNegotiationView(APIView):
         """
         An example view that does not perform content negotiation.

docs/api-guide/exceptions.md

-<a class="github" href="exceptions.py"></a>
+source: exceptions.py
 
 # Exceptions
 
@@ -18,7 +18,7 @@ The handled exceptions are:
 
 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.
+Most error responses will include a key `detail` in the body of the response.
 
 For example, the following request:
 
@@ -28,28 +28,91 @@ For example, the following request:
 Might receive an error response indicating that the `DELETE` method is not allowed on that resource:
 
     HTTP/1.1 405 Method Not Allowed
-    Content-Type: application/json; charset=utf-8
+    Content-Type: application/json
     Content-Length: 42
-    
+
     {"detail": "Method 'DELETE' not allowed."}
 
+Validation errors are handled slightly differently, and will include the field names as the keys in the response. If the validation error was not specific to a particular field then it will use the "non_field_errors" key, or whatever string value has been set for the `NON_FIELD_ERRORS_KEY` setting.
+
+Any example validation error might look like this:
+
+    HTTP/1.1 400 Bad Request
+    Content-Type: application/json
+    Content-Length: 94
+
+    {"amount": ["A valid integer is required."], "description": ["This field may not be blank."]}
+
+## Custom exception handling
+
+You can implement custom exception handling by creating a handler function that converts exceptions raised in your API views into response objects.  This allows you to control the style of error responses used by your API.
+
+The function must take a pair of arguments, this first is the exception to be handled, and the second is a dictionary containing any extra context such as the view currently being handled. The exception handler function should either return a `Response` object, or return `None` if the exception cannot be handled.  If the handler returns `None` then the exception will be re-raised and Django will return a standard HTTP 500 'server error' response.
+
+For example, you might want to ensure that all error responses include the HTTP status code in the body of the response, like so:
+
+    HTTP/1.1 405 Method Not Allowed
+    Content-Type: application/json
+    Content-Length: 62
+
+    {"status_code": 405, "detail": "Method 'DELETE' not allowed."}
+
+In order to alter the style of the response, you could write the following custom exception handler:
+
+    from rest_framework.views import exception_handler
+
+    def custom_exception_handler(exc, context):
+        # Call REST framework's default exception handler first,
+        # to get the standard error response.
+        response = exception_handler(exc, context)
+
+        # Now add the HTTP status code to the response.
+        if response is not None:
+            response.data['status_code'] = response.status_code
+
+        return response
+
+The context argument is not used by the default handler, but can be useful if the exception handler needs further information such as the view currently being handled, which can be accessed as `context['view']`.
+
+The exception handler must also be configured in your settings, using the `EXCEPTION_HANDLER` setting key. For example:
+
+    REST_FRAMEWORK = {
+        'EXCEPTION_HANDLER': 'my_project.my_app.utils.custom_exception_handler'
+    }
+
+If not specified, the `'EXCEPTION_HANDLER'` setting defaults to the standard exception handler provided by REST framework:
+
+    REST_FRAMEWORK = {
+        'EXCEPTION_HANDLER': 'rest_framework.views.exception_handler'
+    }
+
+Note that the exception handler will only be called for responses generated by raised exceptions.  It will not be used for any responses returned directly by the view, such as the `HTTP_400_BAD_REQUEST` responses that are returned by the generic views when serializer validation fails.
+
 ---
 
 # API Reference
 
 ## APIException
 
-**Signature:** `APIException(detail=None)`
+**Signature:** `APIException()`
+
+The **base class** for all exceptions raised inside an `APIView` class or `@api_view`.
+
+To provide a custom exception, subclass `APIException` and set the `.status_code` and `.default_detail` properties on the class.
 
-The **base class** for all exceptions raised inside REST framework.
+For example, if your API relies on a third party service that may sometimes be unreachable, you might want to implement an exception for the "503 Service Unavailable" HTTP response code.  You could do this like so:
 
-To provide a custom exception, subclass `APIException` and set the `.status_code` and `.detail` properties on the class.
+    from rest_framework.exceptions import APIException
+
+    class ServiceUnavailable(APIException):
+        status_code = 503
+        default_detail = 'Service temporarily unavailable, try again later.'
 
 ## ParseError
 
 **Signature:** `ParseError(detail=None)`
 
-Raised if the request contains malformed data when accessing `request.DATA` or `request.FILES`.
+Raised if the request contains malformed data when accessing `request.data`.
 
 By default this exception results in a response with the HTTP status code "400 Bad Request".
 
@@ -77,6 +140,14 @@ Raised when an authenticated request fails the permission checks.
 
 By default this exception results in a response with the HTTP status code "403 Forbidden".
 
+## NotFound
+
+**Signature:** `NotFound(detail=None)`
+
+Raised when a resource does not exists at the given URL. This exception is equivalent to the standard `Http404` Django exception.
+
+By default this exception results in a response with the HTTP status code "404 Not Found".
+
 ## MethodNotAllowed
 
 **Signature:** `MethodNotAllowed(method, detail=None)`
@@ -85,11 +156,19 @@ Raised when an incoming request occurs that does not map to a handler method on
 
 By default this exception results in a response with the HTTP status code "405 Method Not Allowed".
 
+## NotAcceptable
+
+**Signature:** `NotAcceptable(detail=None)`
+
+Raised when an incoming request occurs with an `Accept` header that cannot be satisfied by any of the available renderers.
+
+By default this exception results in a response with the HTTP status code "406 Not Acceptable".
+
 ## UnsupportedMediaType
 
 **Signature:** `UnsupportedMediaType(media_type, detail=None)`
 
-Raised if there are no parsers that can handle the content type of the request data when accessing `request.DATA` or `request.FILES`.
+Raised if there are no parsers that can handle the content type of the request data when accessing `request.data`.
 
 By default this exception results in a response with the HTTP status code "415 Unsupported Media Type".
 
@@ -101,5 +180,23 @@ Raised when an incoming request fails the throttling checks.
 
 By default this exception results in a response with the HTTP status code "429 Too Many Requests".
 
+## ValidationError
+
+**Signature:** `ValidationError(detail)`
+
+The `ValidationError` exception is slightly different from the other `APIException` classes:
+
+* The `detail` argument is mandatory, not optional.
+* The `detail` argument may be a list or dictionary of error details, and may also be a nested data structure.
+* By convention you should import the serializers module and use a fully qualified `ValidationError` style, in order to differentiate it from Django's built-in validation error. For example. `raise serializers.ValidationError('This field must be an integer value.')`
+
+The `ValidationError` class should be used for serializer and field validation, and by validator classes. It is also raised when calling `serializer.is_valid` with the `raise_exception` keyword argument:
+
+    serializer.is_valid(raise_exception=True)
+
+The generic views use the `raise_exception=True` flag, which means that you can override the style of validation error responses globally in your API. To do so, use a custom exception handler, as described above.
+
+By default this exception results in a response with the HTTP status code "400 Bad Request".
+
 [cite]: http://www.doughellmann.com/articles/how-tos/python-exception-handling/index.html
 [authentication]: authentication.md

docs/api-guide/format-suffixes.md

-<a class="github" href="urlpatterns.py"></a>
+source: urlpatterns.py
 
 # Format suffixes
 
@@ -7,7 +7,7 @@ used all the time.
 >
 > &mdash; Roy Fielding, [REST discuss mailing list][cite]
 
-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. 
+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.
 
@@ -21,18 +21,19 @@ 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. 
+* **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'^comments/$', 'comment_list'),
-        url(r'^comments/(?P<pk>[0-9]+)/$', 'comment_detail')
-    )
-    
+    from blog import views
+
+    urlpatterns = [
+        url(r'^/$', views.apt_root),
+        url(r'^comments/$', views.comment_list),
+        url(r'^comments/(?P<pk>[0-9]+)/$', views.comment_detail)
+    ]
+
     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:
@@ -54,13 +55,25 @@ The name of the kwarg used may be modified by using the `FORMAT_SUFFIX_KWARG` se
 
 Also note that `format_suffix_patterns` does not support descending into `include` URL patterns.
 
+### Using with `i18n_patterns`
+
+If using the `i18n_patterns` function provided by Django, as well as `format_suffix_patterns` you should make sure that the `i18n_patterns` function is applied as the final, or outermost function. For example:
+
+    url patterns = [
+        …
+    ]
+
+    urlpatterns = i18n_patterns(
+        format_suffix_patterns(urlpatterns, allowed=['json', 'html'])
+    )
+
 ---
-        
+
 ## 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: 
+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]
 

docs/api-guide/metadata.md

+source: metadata.py
+
+# Metadata
+
+> [The `OPTIONS`] method allows a client to determine the options and/or requirements associated with a resource, or the capabilities of a server, without implying a resource action or initiating a resource retrieval.
+>
+> — [RFC7231, Section 4.3.7.][cite]
+
+REST framework includes a configurable mechanism for determining how your API should respond to `OPTIONS` requests. This allows you to return API schema or other resource information.
+
+There are not currently any widely adopted conventions for exactly what style of response should be returned for HTTP `OPTIONS` requests, so we provide an ad-hoc style that returns some useful information.
+
+Here's an example response that demonstrates the information that is returned by default.
+
+    HTTP 200 OK
+    Allow: GET, POST, HEAD, OPTIONS
+    Content-Type: application/json
+
+    {
+        "name": "To Do List",
+        "description": "List existing 'To Do' items, or create a new item.",
+        "renders": [
+            "application/json",
+            "text/html"
+        ],
+        "parses": [
+            "application/json",
+            "application/x-www-form-urlencoded",
+            "multipart/form-data"
+        ],
+        "actions": {
+            "POST": {
+                "note": {
+                    "type": "string",
+                    "required": false,
+                    "read_only": false,
+                    "label": "title",
+                    "max_length": 100
+                }
+            }
+        }
+    }
+
+## Setting the metadata scheme
+
+You can set the metadata class globally using the `'DEFAULT_METADATA_CLASS'` settings key:
+
+    REST_FRAMEWORK = {
+        'DEFAULT_METADATA_CLASS': 'rest_framework.metadata.SimpleMetadata'
+    }
+
+Or you can set the metadata class individually for a view:
+
+    class APIRoot(APIView):
+        metadata_class = APIRootMetadata
+
+        def get(self, request, format=None):
+            return Response({
+                ...
+            })
+
+The REST framework package only includes a single metadata class implementation, named `SimpleMetadata`. If you want to use an alternative style you'll need to implement a custom metadata class.
+
+## Creating schema endpoints
+
+If you have specific requirements for creating schema endpoints that are accessed with regular `GET` requests, you might consider re-using the metadata API for doing so.
+
+For example, the following additional route could be used on a viewset to provide a linkable schema endpoint.
+
+    @list_route(methods=['GET'])
+    def schema(self, request):
+        meta = self.metadata_class()
+        data = meta.determine_metadata(request, self)
+        return Response(data)
+
+There are a couple of reasons that you might choose to take this approach, including that `OPTIONS` responses [are not cacheable][no-options].
+
+---
+
+# Custom metadata classes
+
+If you want to provide a custom metadata class you should override `BaseMetadata` and implement the `determine_metadata(self, request, view)` method.
+
+Useful things that you might want to do could include returning schema information, using a format such as [JSON schema][json-schema], or returning debug information to admin users.
+
+## Example
+
+The following class could be used to limit the information that is returned to `OPTIONS` requests.
+
+    class MinimalMetadata(BaseMetadata):
+        """
+        Don't include field and other information for `OPTIONS` requests.
+        Just return the name and description.
+        """
+        def determine_metadata(self, request, view):
+            return {
+                'name': view.get_view_name(),
+                'description': view.get_view_description()
+            }
+
+[cite]: http://tools.ietf.org/html/rfc7231#section-4.3.7
+[no-options]: https://www.mnot.net/blog/2012/10/29/NO_OPTIONS
+[json-schema]: http://json-schema.org/

docs/api-guide/parsers.md

-<a class="github" href="parsers.py"></a>
+source: parsers.py
 
 # Parsers
 
@@ -12,7 +12,7 @@ REST framework includes a number of built in Parser classes, that allow you to a
 
 ## How the parser is determined
 
-The set of valid parsers for a view is always defined as a list of classes.  When either `request.DATA` or `request.FILES` is accessed, REST framework will examine the `Content-Type` header on the incoming request, and determine which parser to use to parse the request content.
+The set of valid parsers for a view is always defined as a list of classes.  When  `request.data` is accessed, REST framework will examine the `Content-Type` header on the incoming request, and determine which parser to use to parse the request content.
 
 ---
 
@@ -26,35 +26,39 @@ As an example, if you are sending `json` encoded data using jQuery with the [.aj
 
 ## Setting the parsers
 
-The default set of parsers may be set globally, using the `DEFAULT_PARSER_CLASSES` setting.  For example, the following settings would allow requests with `YAML` content.
+The default set of parsers may be set globally, using the `DEFAULT_PARSER_CLASSES` setting. For example, the following settings would allow only requests with `JSON` content, instead of the default of JSON or form data.
 
     REST_FRAMEWORK = {
         'DEFAULT_PARSER_CLASSES': (
-            'rest_framework.parsers.YAMLParser',
+            'rest_framework.parsers.JSONParser',
         )
     }
 
-You can also set the renderers used for an individual view, or viewset,
+You can also set the parsers used for an individual view, or viewset,
 using the `APIView` class based views.
 
+    from rest_framework.parsers import JSONParser
+    from rest_framework.response import Response
+    from rest_framework.views import APIView
+
     class ExampleView(APIView):
         """
-        A view that can accept POST requests with YAML content.
+        A view that can accept POST requests with JSON content.
         """
-        parser_classes = (YAMLParser,)
+        parser_classes = (JSONParser,)
 
         def post(self, request, format=None):
-            return Response({'received data': request.DATA})
+            return Response({'received data': request.data})
 
 Or, if you're using the `@api_view` decorator with function based views.
 
     @api_view(['POST'])
-    @parser_classes((YAMLParser,))
+    @parser_classes((JSONParser,))
     def example_view(request, format=None):
         """
-        A view that can accept POST requests with YAML content.
+        A view that can accept POST requests with JSON content.
         """
-        return Response({'received data': request.DATA})
+        return Response({'received data': request.data})
 
 ---
 
@@ -66,29 +70,9 @@ Parses `JSON` request content.
 
 **.media_type**: `application/json`
 
-## YAMLParser
-
-Parses `YAML` request content.
-
-Requires the `pyyaml` package to be installed.
-
-**.media_type**: `application/yaml`
-
-## XMLParser
-
-Parses REST framework's default style of `XML` request content.
-
-Note that the `XML` markup language is typically used as the base language for more strictly defined domain-specific languages, such as `RSS`, `Atom`, and `XHTML`.
-
-If you are considering using `XML` for your API, you may want to consider implementing a custom renderer and parser for your specific requirements, and using an existing domain-specific media-type, or creating your own custom XML-based media-type.
-
-Requires the `defusedxml` package to be installed.
-
-**.media_type**: `application/xml`
-
 ## FormParser
 
-Parses HTML form content.  `request.DATA` will be populated with a `QueryDict` of data, `request.FILES` will be populated with an empty `QueryDict` of data.
+Parses HTML form content.  `request.data` will be populated with a `QueryDict` of data.
 
 You will typically want to use both `FormParser` and `MultiPartParser` together in order to fully support HTML form data.
 
@@ -96,7 +80,7 @@ You will typically want to use both `FormParser` and `MultiPartParser` together
 
 ## MultiPartParser
 
-Parses multipart HTML form content, which supports file uploads.  Both `request.DATA` and `request.FILES` will be populated with a `QueryDict`.
+Parses multipart HTML form content, which supports file uploads.  Both `request.data` will be populated with a `QueryDict`.
 
 You will typically want to use both `FormParser` and `MultiPartParser` together in order to fully support HTML form data.
 
@@ -104,7 +88,7 @@ You will typically want to use both `FormParser` and `MultiPartParser` together
 
 ## FileUploadParser
 
-Parses raw file upload content.  The `request.DATA` property will be an empty `QueryDict`, and `request.FILES` will be a dictionary with a single key `'file'` containing the uploaded file.
+Parses raw file upload content.  The `request.data` property will be a dictionary with a single key `'file'` containing the uploaded file.
 
 If the view used with `FileUploadParser` is called with a `filename` URL keyword argument, then that argument will be used as the filename.  If it is called without a `filename` URL keyword argument, then the client must set the filename in the `Content-Disposition` HTTP header.  For example `Content-Disposition: attachment; filename=upload.jpg`.
 
@@ -122,9 +106,9 @@ If the view used with `FileUploadParser` is called with a `filename` URL keyword
         parser_classes = (FileUploadParser,)
 
         def put(self, request, filename, format=None):
-            file_obj = request.FILES['file']
+            file_obj = request.data['file']
             # ...
-            # do some staff with uploaded file
+            # do some stuff with uploaded file
             # ...
             return Response(status=204)
 
@@ -135,7 +119,7 @@ If the view used with `FileUploadParser` is called with a `filename` URL keyword
 
 To implement a custom parser, you should override `BaseParser`, set the `.media_type` property, and implement the `.parse(self, stream, media_type, parser_context)` method.
 
-The method should return the data that will be used to populate the `request.DATA` property.
+The method should return the data that will be used to populate the `request.data` property.
 
 The arguments passed to `.parse()` are:
 
@@ -157,7 +141,7 @@ By default this will include the following keys: `view`, `request`, `args`, `kwa
 
 ## Example
 
-The following is an example plaintext parser that will populate the `request.DATA` property with a string representing the body of the request. 
+The following is an example plaintext parser that will populate the `request.data` property with a string representing the body of the request.
 
     class PlainTextParser(BaseParser):
     """
@@ -178,13 +162,64 @@ The following is an example plaintext parser that will populate the `request.DAT
 
 The following third party packages are also available.
 
+## YAML
+
+[REST framework YAML][rest-framework-yaml] provides [YAML][yaml] parsing and rendering support. It was previously included directly in the REST framework package, and is now instead supported as a third-party package.
+
+#### Installation & configuration
+
+Install using pip.
+
+    $ pip install djangorestframework-yaml
+
+Modify your REST framework settings.
+
+    REST_FRAMEWORK = {
+        'DEFAULT_PARSER_CLASSES': (
+            'rest_framework_yaml.parsers.YAMLParser',
+        ),
+        'DEFAULT_RENDERER_CLASSES': (
+            'rest_framework_yaml.renderers.YAMLRenderer',
+        ),
+    }
+
+## XML
+
+[REST Framework XML][rest-framework-xml] provides a simple informal XML format. It was previously included directly in the REST framework package, and is now instead supported as a third-party package.
+
+#### Installation & configuration
+
+Install using pip.
+
+    $ pip install djangorestframework-xml
+
+Modify your REST framework settings.
+
+    REST_FRAMEWORK = {
+        'DEFAULT_PARSER_CLASSES': (
+            'rest_framework_xml.parsers.XMLParser',
+        ),
+        'DEFAULT_RENDERER_CLASSES': (
+            'rest_framework_xml.renderers.XMLRenderer',
+        ),
+    }
+
 ## MessagePack
 
 [MessagePack][messagepack] is a fast, efficient binary serialization format.  [Juan Riaza][juanriaza] maintains the [djangorestframework-msgpack][djangorestframework-msgpack] package which provides MessagePack renderer and parser support for REST framework.
 
+## CamelCase JSON
+
+[djangorestframework-camel-case] provides camel case JSON renderers and parsers for REST framework.  This allows serializers to use Python-style underscored field names, but be exposed in the API as Javascript-style camel case field names.  It is maintained by [Vitaly Babiy][vbabiy].
+
 [jquery-ajax]: http://api.jquery.com/jQuery.ajax/
 [cite]: https://groups.google.com/d/topic/django-developers/dxI4qVzrBY4/discussion
 [upload-handlers]: https://docs.djangoproject.com/en/dev/topics/http/file-uploads/#upload-handlers
+[rest-framework-yaml]: http://jpadilla.github.io/django-rest-framework-yaml/
+[rest-framework-xml]: http://jpadilla.github.io/django-rest-framework-xml/
+[yaml]: http://www.yaml.org/
 [messagepack]: https://github.com/juanriaza/django-rest-framework-msgpack
 [juanriaza]: https://github.com/juanriaza
+[vbabiy]: https://github.com/vbabiy
 [djangorestframework-msgpack]: https://github.com/juanriaza/django-rest-framework-msgpack
+[djangorestframework-camel-case]: https://github.com/vbabiy/djangorestframework-camel-case

docs/api-guide/requests.md

-<a class="github" href="request.py"></a>
+source: request.py
 
 # Requests
 
@@ -14,26 +14,29 @@ REST framework's `Request` class extends the standard `HttpRequest`, adding supp
 
 REST framework's Request objects provide flexible request parsing that allows you to treat requests with JSON data or other media types in the same way that you would normally deal with form data.
 
-## .DATA
+## .data
 
-`request.DATA` returns the parsed content of the request body.  This is similar to the standard `request.POST` attribute except that:
+`request.data` returns the parsed content of the request body.  This is similar to the standard `request.POST` and `request.FILES` attributes except that:
 
+* It includes all parsed content, including *file and non-file* inputs.
 * It supports parsing the content of HTTP methods other than `POST`, meaning that you can access the content of `PUT` and `PATCH` requests.
 * It supports REST framework's flexible request parsing, rather than just supporting form data.  For example you can handle incoming JSON data in the same way that you handle incoming form data.
 
 For more details see the [parsers documentation].
 
-## .FILES
+## .query_params
 
-`request.FILES` returns any uploaded files that may be present in the content of the request body.  This is the same as the standard `HttpRequest` behavior, except that the same flexible request parsing is used for `request.DATA`.
+`request.query_params` is a more correctly named synonym for `request.GET`.
 
-For more details see the [parsers documentation].
+For clarity inside your code, we recommend using `request.query_params` instead of the Django's standard `request.GET`. Doing so will help keep your codebase more correct and obvious - any HTTP method type may include query parameters, not just `GET` requests.
 
-## .QUERY_PARAMS
+## .DATA and .FILES
+
+The old-style version 2.x `request.DATA` and `request.FILES` attributes are still available, but are now pending deprecation in favor of the unified `request.data` attribute.
 
-`request.QUERY_PARAMS` is a more correctly named synonym for `request.GET`.
+## .QUERY_PARAMS
 
-For clarity inside your code, we recommend using `request.QUERY_PARAMS` instead of the usual `request.GET`, as *any* HTTP method type may include query parameters.
+The old-style version 2.x `request.QUERY_PARAMS` attribute is still available, but is now pending deprecation in favor of the more pythonic `request.query_params`.
 
 ## .parsers
 
@@ -43,12 +46,26 @@ You won't typically need to access this property.
 
 ---
 
-**Note:** If a client sends malformed content, then accessing `request.DATA` or `request.FILES` may raise a `ParseError`.  By default REST framework's `APIView` class or `@api_view` decorator will catch the error and return a `400 Bad Request` response.
+**Note:** If a client sends malformed content, then accessing `request.data` may raise a `ParseError`.  By default REST framework's `APIView` class or `@api_view` decorator will catch the error and return a `400 Bad Request` response.
 
 If a client sends a request with a content-type that cannot be parsed then a `UnsupportedMediaType` exception will be raised, which by default will be caught and return a `415 Unsupported Media Type` response.
 
 ---
 
+# Content negotiation
+
+The request exposes some properties that allow you to determine the result of the content negotiation stage. This allows you to implement behaviour such as selecting a different serialisation schemes for different media types.
+
+## .accepted_renderer
+
+The renderer instance what was selected by the content negotiation stage.
+
+## .accepted_media_type
+
+A string representing the media type that was accepted by the content negotiation stage.
+
+---
+
 # Authentication
 
 REST framework provides flexible, per-request authentication, that gives you the ability to:
@@ -91,7 +108,7 @@ REST framework supports a few browser enhancements such as browser-based `PUT`,
 
 Browser-based `PUT`, `PATCH` and `DELETE` forms are transparently supported.
 
-For more information see the [browser enhancements documentation].    
+For more information see the [browser enhancements documentation].
 
 ## .content_type
 
@@ -101,7 +118,7 @@ You won't typically need to directly access the request's content type, as you'l
 
 If you do need to access the content type of the request you should use the `.content_type` property in preference to using `request.META.get('HTTP_CONTENT_TYPE')`, as it provides transparent support for browser-based non-form content.
 
-For more information see the [browser enhancements documentation].    
+For more information see the [browser enhancements documentation].
 
 ## .stream
 
@@ -111,13 +128,13 @@ You won't typically need to directly access the request's content, as you'll nor
 
 If you do need to access the raw content directly, you should use the `.stream` property in preference to using `request.content`, as it provides transparent support for browser-based non-form content.
 
-For more information see the [browser enhancements documentation].    
+For more information see the [browser enhancements documentation].
 
 ---
 
 # Standard HttpRequest attributes
 
-As REST framework's `Request` extends Django's `HttpRequest`, all the other standard attributes and methods are also available.  For example the `request.META` dictionary is available as normal.
+As REST framework's `Request` extends Django's `HttpRequest`, all the other standard attributes and methods are also available.  For example the `request.META` and `request.session` dictionaries are available as normal.
 
 Note that due to implementation reasons the `Request` class does not inherit from `HttpRequest` class, but instead extends the class using composition.
 

docs/api-guide/responses.md

-<a class="github" href="response.py"></a>
+source: response.py
 
 # Responses
 
@@ -24,7 +24,7 @@ Unless you want to heavily customize REST framework for some reason, you should
 
 Unlike regular `HttpResponse` objects, you do not instantiate `Response` objects with rendered content.  Instead you pass in unrendered data, which may consist of any Python primitives.
 
-The renderers used by the `Response` class cannot natively handle complex datatypes such as Django model instances, so you need to serialize the data into primative datatypes before creating the `Response` object.
+The renderers used by the `Response` class cannot natively handle complex datatypes such as Django model instances, so you need to serialize the data into primitive datatypes before creating the `Response` object.
 
 You can use REST framework's `Serializer` classes to perform this data serialization, or use your own custom serialization.
 
@@ -54,7 +54,7 @@ The rendered content of the response.  The `.render()` method must have been cal
 
 ## .template_name
 
-The `template_name`, if supplied.  Only required if `HTMLRenderer` or some other custom template renderer is the accepted renderer for the reponse.
+The `template_name`, if supplied.  Only required if `HTMLRenderer` or some other custom template renderer is the accepted renderer for the response.
 
 ## .accepted_renderer
 
@@ -90,6 +90,6 @@ The `Response` class extends `SimpleTemplateResponse`, and all the usual attribu
 As with any other `TemplateResponse`, this method is called to render the serialized data of the response into the final response content.  When `.render()` is called, the response content will be set to the result of calling the `.render(data, accepted_media_type, renderer_context)` method on the `accepted_renderer` instance.
 
 You won't typically need to call `.render()` yourself, as it's handled by Django's standard response cycle.
-    
+
 [cite]: https://docs.djangoproject.com/en/dev/ref/template-response/
 [statuscodes]: status-codes.md

docs/api-guide/reverse.md

-<a class="github" href="reverse.py"></a>
+source: reverse.py
 
 # Returning URLs
 
@@ -17,7 +17,7 @@ The advantages of doing so are:
 
 REST framework provides two utility functions to make it more simple to return absolute URIs from your Web API.
 
-There's no requirement for you to use them, but if you do then the self-describing API will be able to automatically hyperlink it's output for you, which makes browsing the API much easier.
+There's no requirement for you to use them, but if you do then the self-describing API will be able to automatically hyperlink its output for you, which makes browsing the API much easier.
 
 ## reverse
 
@@ -27,13 +27,13 @@ Has the same behavior as [`django.core.urlresolvers.reverse`][reverse], except t
 
 You should **include the request as a keyword argument** to the function, for example:
 
-    import datetime
     from rest_framework.reverse import reverse
     from rest_framework.views import APIView
-   
+	from django.utils.timezone import now
+
 	class APIRootView(APIView):
 	    def get(self, request):
-	        year = datetime.datetime.now().year
+	        year = now().year
 			data = {
  				...
     		    'year-summary-url': reverse('year-summary', args=[year], request=request)

docs/api-guide/status-codes.md

-<a class="github" href="status.py"></a>
+source: status.py
 
 # Status Codes
 
@@ -9,6 +9,7 @@
 Using bare status codes in your responses isn't recommended.  REST framework includes a set of named constants that you can use to make more code more obvious and readable.
 
     from rest_framework import status
+    from rest_framework.response import Response
 
     def empty_view(self):
         content = {'please move along': 'nothing to see here'}
@@ -16,6 +17,18 @@ Using bare status codes in your responses isn't recommended.  REST framework inc
 
 The full set of HTTP status codes included in the `status` module is listed below.
 
+The module also includes a set of helper functions for testing if a status code is in a given range.
+
+    from rest_framework import status
+	from rest_framework.test import APITestCase
+
+	class ExampleTestCase(APITestCase):
+	    def test_url_root(self):
+	        url = reverse('index')
+	        response = self.client.get(url)
+	        self.assertTrue(status.is_success(response.status_code))
+
+
 For more information on proper usage of HTTP status codes see [RFC 2616][rfc2616]
 and [RFC 6585][rfc6585].
 
@@ -38,7 +51,7 @@ This class of status code indicates that the client's request was successfully r
     HTTP_205_RESET_CONTENT
     HTTP_206_PARTIAL_CONTENT
 
-## Redirection - 3xx 
+## Redirection - 3xx
 
 This class of status code indicates that further action needs to be taken by the user agent in order to fulfill the request.
 
@@ -89,6 +102,15 @@ Response status codes beginning with the digit "5" indicate cases in which the s
     HTTP_505_HTTP_VERSION_NOT_SUPPORTED
     HTTP_511_NETWORK_AUTHENTICATION_REQUIRED
 
+## Helper functions
+
+The following helper functions are available for identifying the category of the response code.
+
+    is_informational()  # 1xx
+    is_success()        # 2xx
+    is_redirect()       # 3xx
+    is_client_error()   # 4xx
+    is_server_error()   # 5xx
 
 [rfc2324]: http://www.ietf.org/rfc/rfc2324.txt
 [rfc2616]: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html

docs/api-guide/testing.md

-<a class="github" href="test.py"></a>
+source: test.py
 
 # Testing
 
-> Code without tests is broken as designed
+> Code without tests is broken as designed.
 >
 > &mdash; [Jacob Kaplan-Moss][cite]
 
@@ -14,7 +14,9 @@ Extends [Django's existing `RequestFactory` class][requestfactory].
 
 ## Creating test requests
 
-The `APIRequestFactory` class supports an almost identical API to Django's standard `RequestFactory` class.  This means the that standard `.get()`, `.post()`, `.put()`, `.patch()`, `.delete()`, `.head()` and `.options()` methods are all available.
+The `APIRequestFactory` class supports an almost identical API to Django's standard `RequestFactory` class.  This means that the standard `.get()`, `.post()`, `.put()`, `.patch()`, `.delete()`, `.head()` and `.options()` methods are all available.
+
+    from rest_framework.test import APIRequestFactory
 
     # Using the standard RequestFactory API to create a form POST request
     factory = APIRequestFactory()
@@ -34,7 +36,7 @@ To support a wider set of request formats, or change the default format, [see th
 
 #### Explicitly encoding the request body
 
-If you need to explictly encode the request body, you can do so by setting the `content_type` flag.  For example:
+If you need to explicitly encode the request body, you can do so by setting the `content_type` flag.  For example:
 
     request = factory.post('/notes/', json.dumps({'title': 'new idea'}), content_type='application/json')
 
@@ -49,6 +51,8 @@ For example, using `APIRequestFactory`, you can make a form PUT request like so:
 
 Using Django's `RequestFactory`, you'd need to explicitly encode the data yourself:
 
+    from django.test.client import encode_multipart, RequestFactory
+
     factory = RequestFactory()
     data = {'title': 'remember to email dave'}
     content = encode_multipart('BoUnDaRyStRiNg', data)
@@ -61,6 +65,8 @@ When testing views directly using a request factory, it's often convenient to be
 
 To forcibly authenticate a request, use the `force_authenticate()` method.
 
+    from rest_framework.tests import force_authenticate
+
     factory = APIRequestFactory()
     user = User.objects.get(username='olivia')
     view = AccountDetail.as_view()
@@ -72,6 +78,12 @@ To forcibly authenticate a request, use the `force_authenticate()` method.
 
 The signature for the method is `force_authenticate(request, user=None, token=None)`.  When making the call, either or both of the user and token may be set.
 
+For example, when forcibly authenticating using a token, you might do something like the following:
+
+    user = User.objects.get(username='olivia')
+    request = factory.get('/accounts/django-superstars/')
+    force_authenticate(request, user=user, token=user.token)
+
 ---
 
 **Note**: When using `APIRequestFactory`, the object that is returned is Django's standard `HttpRequest`, and not REST framework's `Request` object, which is only generated once the view is called.
@@ -103,7 +115,9 @@ Extends [Django's existing `Client` class][client].
 
 ## Making requests
 
-The `APIClient` class supports the same request interface as `APIRequestFactory`.  This means the that standard `.get()`, `.post()`, `.put()`, `.patch()`, `.delete()`, `.head()` and `.options()` methods are all available.  For example:
+The `APIClient` class supports the same request interface as Django's standard `Client` class.  This means the that standard `.get()`, `.post()`, `.put()`, `.patch()`, `.delete()`, `.head()` and `.options()` methods are all available.  For example:
+
+    from rest_framework.test import APIClient
 
     client = APIClient()
     client.post('/notes/', {'title': 'new idea'}, format='json')
@@ -131,8 +145,11 @@ The `login` method is appropriate for testing APIs that use session authenticati
 
 The `credentials` method can be used to set headers that will then be included on all subsequent requests by the test client.
 
+    from rest_framework.authtoken.models import Token
+    from rest_framework.test import APIClient
+
     # Include an appropriate `Authorization:` header on all requests.
-    token = Token.objects.get(username='lauren')
+    token = Token.objects.get(user__username='lauren')
     client = APIClient()
     client.credentials(HTTP_AUTHORIZATION='Token ' + token.key)
 
@@ -155,7 +172,7 @@ This can be a useful shortcut if you're testing the API but don't want to have t
 
 To unauthenticate subsequent requests, call `force_authenticate` setting the user and/or token to `None`.
 
-    client.force_authenticate(user=None) 
+    client.force_authenticate(user=None)
 
 ## CSRF validation
 
@@ -182,7 +199,7 @@ You can use any of REST framework's test case classes as you would for the regul
 
     from django.core.urlresolvers import reverse
     from rest_framework import status
-    from rest_framework.test import APITestCase 
+    from rest_framework.test import APITestCase
 
     class AccountTests(APITestCase):
         def test_create_account(self):
@@ -203,12 +220,12 @@ You can use any of REST framework's test case classes as you would for the regul
 
 When checking the validity of test responses it's often more convenient to inspect the data that the response was created with, rather than inspecting the fully rendered response.
 
-For example, it's easier to inspect `request.data`:
+For example, it's easier to inspect `response.data`:
 
     response = self.client.get('/users/4/')
     self.assertEqual(response.data, {'id': 4, 'username': 'lauren'})
 
-Instead of inspecting the result of parsing `request.content`:
+Instead of inspecting the result of parsing `response.content`:
 
     response = self.client.get('/users/4/')
     self.assertEqual(json.loads(response.content), {'id': 4, 'username': 'lauren'})
@@ -240,18 +257,18 @@ The default format used to make test requests may be set using the `TEST_REQUEST
 
 If you need to test requests using something other than multipart or json requests, you can do so by setting the `TEST_REQUEST_RENDERER_CLASSES` setting.
 
-For example, to add support for using `format='yaml'` in test requests, you might have something like this in your `settings.py` file.
+For example, to add support for using `format='html'` in test requests, you might have something like this in your `settings.py` file.
 
     REST_FRAMEWORK = {
         ...
         'TEST_REQUEST_RENDERER_CLASSES': (
             'rest_framework.renderers.MultiPartRenderer',
             'rest_framework.renderers.JSONRenderer',
-            'rest_framework.renderers.YAMLRenderer'
+            'rest_framework.renderers.TemplateHTMLRenderer'
         )
     }
 
 [cite]: http://jacobian.org/writing/django-apps-with-buildout/#s-create-a-test-wrapper
-[client]: https://docs.djangoproject.com/en/dev/topics/testing/overview/#module-django.test.client
+[client]: https://docs.djangoproject.com/en/dev/topics/testing/tools/#the-test-client
 [requestfactory]: https://docs.djangoproject.com/en/dev/topics/testing/advanced/#django.test.client.RequestFactory
 [configuration]: #configuration

docs/api-guide/throttling.md

-<a class="github" href="throttling.py"></a>
+source: throttling.py
 
 # Throttling
 
@@ -35,7 +35,7 @@ The default throttling policy may be set globally, using the `DEFAULT_THROTTLE_C
         'DEFAULT_THROTTLE_RATES': {
             'anon': '100/day',
             'user': '1000/day'
-        }        
+        }
     }
 
 The rate descriptions used in `DEFAULT_THROTTLE_RATES` may include `second`, `minute`, `hour` or `day` as the throttle period.
@@ -43,6 +43,10 @@ The rate descriptions used in `DEFAULT_THROTTLE_RATES` may include `second`, `mi
 You can also set the throttling policy on a per-view or per-viewset basis,
 using the `APIView` class based views.
 
+	from rest_framework.response import Response
+    from rest_framework.throttling import UserRateThrottle
+	from rest_framework.views import APIView
+
     class ExampleView(APIView):
         throttle_classes = (UserRateThrottle,)
 
@@ -54,18 +58,35 @@ using the `APIView` class based views.
 
 Or, if you're using the `@api_view` decorator with function based views.
 
-    @api_view('GET')
-    @throttle_classes(UserRateThrottle)
+    @api_view(['GET'])
+    @throttle_classes([UserRateThrottle])
     def example_view(request, format=None):
         content = {
             'status': 'request was permitted'
         }
         return Response(content)
 
+## How clients are identified
+
+The `X-Forwarded-For` and `Remote-Addr` HTTP headers are used to uniquely identify client IP addresses for throttling.  If the `X-Forwarded-For` header is present then it will be used, otherwise the value of the `Remote-Addr` header will be used.
+
+If you need to strictly identify unique client IP addresses, you'll need to first configure the number of application proxies that the API runs behind by setting the `NUM_PROXIES` setting.  This setting should be an integer of zero or more.  If set to non-zero then the client IP will be identified as being the last IP address in the `X-Forwarded-For` header, once any application proxy IP addresses have first been excluded.  If set to zero, then the `Remote-Addr` header will always be used as the identifying IP address.
+
+It is important to understand that if you configure the `NUM_PROXIES` setting, then all clients behind a unique [NAT'd](http://en.wikipedia.org/wiki/Network_address_translation) gateway will be treated as a single client.
+
+Further context on how the `X-Forwarded-For` header works, and identifying a remote client IP can be [found here][identifing-clients].
+
 ## Setting up the cache
 
 The throttle classes provided by REST framework use Django's cache backend.  You should make sure that you've set appropriate [cache settings][cache-setting].  The default value of `LocMemCache` backend should be okay for simple setups.  See Django's [cache documentation][cache-docs] for more details.
 
+If you need to use a cache other than `'default'`, you can do so by creating a custom throttle class and setting the `cache` attribute.  For example:
+
+    class CustomAnonRateThrottle(AnonRateThrottle):
+        cache = get_cache('alternate')
+
+You'll need to remember to also set your custom throttle class in the `'DEFAULT_THROTTLE_CLASSES'` settings key, or using the `throttle_classes` view attribute.
+
 ---
 
 # API Reference
@@ -126,20 +147,20 @@ For example, given the following views...
     class ContactListView(APIView):
         throttle_scope = 'contacts'
         ...
-    
+
     class ContactDetailView(ApiView):
         throttle_scope = 'contacts'
         ...
 
-    class UploadView(APIView):        
+    class UploadView(APIView):
         throttle_scope = 'uploads'
         ...
-    
+
 ...and the following settings.
 
     REST_FRAMEWORK = {
         'DEFAULT_THROTTLE_CLASSES': (
-            'rest_framework.throttling.ScopedRateThrottle'
+            'rest_framework.throttling.ScopedRateThrottle',
         ),
         'DEFAULT_THROTTLE_RATES': {
             'contacts': '1000/day',
@@ -157,6 +178,8 @@ To create a custom throttle, override `BaseThrottle` and implement `.allow_reque
 
 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`.
 
+If the `.wait()` method is implemented and the request is throttled, then a `Retry-After` header will be included in the response.
+
 ## Example
 
 The following is an example of a rate throttle, that will randomly throttle 1 in every 10 requests.
@@ -167,5 +190,6 @@ The following is an example of a rate throttle, that will randomly throttle 1 in
 
 [cite]: https://dev.twitter.com/docs/error-codes-responses
 [permissions]: permissions.md
+[identifing-clients]: http://oxpedia.org/wiki/index.php?title=AppSuite:Grizzly#Multiple_Proxies_in_front_of_the_cluster
 [cache-setting]: https://docs.djangoproject.com/en/dev/ref/settings/#caches
 [cache-docs]: https://docs.djangoproject.com/en/dev/topics/cache/#setting-up-the-cache

docs/api-guide/versioning.md

+source: versioning.py
+
+# Versioning
+
+> Versioning an interface is just a "polite" way to kill deployed clients.
+> 
+> — [Roy Fielding][cite].
+
+API versioning allows you to alter behavior between different clients. REST framework provides for a number of different versioning schemes.
+
+Versioning is determined by the incoming client request, and may either be based on the request URL, or based on the request headers.
+
+There are a number of valid approaches to approaching versioning. [Non-versioned systems can also be appropriate][roy-fielding-on-versioning], particularly if you're engineering for very long-term systems with multiple clients outside of your control.
+
+## Versioning with REST framework
+
+When API versioning is enabled, the `request.version` attribute will contain a string that corresponds to the version requested in the incoming client request.
+
+By default, versioning is not enabled, and `request.version` will always return `None`.
+
+#### Varying behavior based on the version
+
+How you vary the API behavior is up to you, but one example you might typically want is to switch to a different serialization style in a newer version. For example:
+
+    def get_serializer_class(self):
+        if self.request.version == 'v1':
+            return AccountSerializerVersion1
+        return AccountSerializer
+
+#### Reversing URLs for versioned APIs
+
+The `reverse` function included by REST framework ties in with the versioning scheme. You need to make sure to include the current `request` as a keyword argument, like so.
+
+    reverse('bookings-list', request=request)
+
+The above function will apply any URL transformations appropriate to the request version. For example:
+
+* If `NamespacedVersioning` was being used, and the API version was 'v1', then the URL lookup used would be `'v1:bookings-list'`, which might resolve to a URL like `http://example.org/v1/bookings/`.
+* If `QueryParameterVersioning` was being used, and the API version was `1.0`, then the returned URL might be something like `http://example.org/bookings/?version=1.0`
+
+#### Versioned APIs and hyperlinked serializers
+
+When using hyperlinked serialization styles together with a URL based versioning scheme make sure to include the request as context to the serializer.
+
+    def get(self, request):
+        queryset = Booking.objects.all()
+        serializer = BookingsSerializer(queryset, many=True, context={'request': request})
+        return Response({'all_bookings': serializer.data})
+
+Doing so will allow any returned URLs to include the appropriate versioning.
+
+## Configuring the versioning scheme
+
+The versioning scheme is defined by the `DEFAULT_VERSIONING_CLASS` settings key.
+
+    REST_FRAMEWORK = {
+        'DEFAULT_VERSIONING_CLASS': 'rest_framework.versioning.NamespaceVersioning'
+    }
+
+Unless it is explicitly set, the value for `DEFAULT_VERSIONING_CLASS` will be `None`. In this case the `request.version` attribute will always return `None`.
+
+You can also set the versioning scheme on an individual view. Typically you won't need to do this, as it makes more sense to have a single versioning scheme used globally. If you do need to do so, use the `versioning_class` attribute.
+
+    class ProfileList(APIView):
+        versioning_class = versioning.QueryParameterVersioning
+
+#### Other versioning settings
+
+The following settings keys are also used to control versioning:
+
+* `DEFAULT_VERSION`. The value that should be used for `request.version` when no versioning information is present. Defaults to `None`.
+* `ALLOWED_VERSIONS`. If set, this value will restrict the set of versions that may be returned by the versioning scheme, and will raise an error if the provided version if not in this set. Defaults to `None`.
+* `VERSION_PARAMETER`. The string that should used for any versioning parameters, such as in the media type or URL query parameters. Defaults to `'version'`.
+
+---
+
+# API Reference
+
+## AcceptHeaderVersioning
+
+This scheme requires the client to specify the version as part of the media type in the `Accept` header. The version is included as a media type parameter, that supplements the main media type.
+
+Here's an example HTTP request using the accept header versioning style.
+
+    GET /bookings/ HTTP/1.1
+    Host: example.com
+    Accept: application/json; version=1.0
+
+In the example request above `request.version` attribute would return the string `'1.0'`.
+
+Versioning based on accept headers is [generally considered][klabnik-guidelines] as [best practice][heroku-guidelines], although other styles may be suitable depending on your client requirements.
+
+#### Using accept headers with vendor media types
+
+Strictly speaking the `json` media type is not specified as [including additional parameters][json-parameters]. If you are building a well-specified public API you might consider using a [vendor media type][vendor-media-type]. To do so, configure your renderers to use a JSON based renderer with a custom media type:
+
+    class BookingsAPIRenderer(JSONRenderer):
+        media_type = 'application/vnd.megacorp.bookings+json'
+
+Your client requests would now look like this:
+
+    GET /bookings/ HTTP/1.1
+    Host: example.com
+    Accept: application/vnd.megacorp.bookings+json; version=1.0
+
+## URLParameterVersioning
+
+This scheme requires the client to specify the version as part of the URL path.
+
+    GET /v1/bookings/ HTTP/1.1
+    Host: example.com
+    Accept: application/json
+
+Your URL conf must include a pattern that matches the version with a `'version'` keyword argument, so that this information is available to the versioning scheme.
+
+    urlpatterns = [
+        url(
+            r'^(?P<version>{v1,v2})/bookings/$',
+            bookings_list,
+            name='bookings-list'
+        ),
+        url(
+            r'^(?P<version>{v1,v2})/bookings/(?P<pk>[0-9]+)/$',
+            bookings_detail,
+            name='bookings-detail'
+        )
+    ]
+
+## NamespaceVersioning
+
+To the client, this scheme is the same as `URLParameterVersioning`. The only difference is how it is configured in your Django application, as it uses URL namespacing, instead of URL keyword arguments.
+
+    GET /v1/something/ HTTP/1.1
+    Host: example.com
+    Accept: application/json
+
+With this scheme the `request.version` attribute is determined based on the `namespace` that matches the incoming request path.
+
+In the following example we're giving a set of views two different possible URL prefixes, each under a different namespace:
+
+    # bookings/urls.py
+    urlpatterns = [
+        url(r'^$', bookings_list, name='bookings-list'),
+        url(r'^(?P<pk>[0-9]+)/$', bookings_detail, name='bookings-detail')
+    ]
+
+    # urls.py
+    urlpatterns = [
+        url(r'^v1/bookings/', include('bookings.urls', namespace='v1')),
+        url(r'^v2/bookings/', include('bookings.urls', namespace='v2'))
+    ]
+
+Both `URLParameterVersioning` and `NamespaceVersioning` are reasonable if you just need a simple versioning scheme. The `URLParameterVersioning` approach might be better suitable for small ad-hoc projects, and the `NamespaceVersioning` is probably easier to manage for larger projects.
+
+## HostNameVersioning
+
+The hostname versioning scheme requires the client to specify the requested version as part of the hostname in the URL.
+
+For example the following is an HTTP request to the `http://v1.example.com/bookings/` URL:
+
+    GET /bookings/ HTTP/1.1
+    Host: v1.example.com
+    Accept: application/json
+
+By default this implementation expects the hostname to match this simple regular expression:
+
+    ^([a-zA-Z0-9]+)\.[a-zA-Z0-9]+\.[a-zA-Z0-9]+$
+
+Note that the first group is enclosed in brackets, indicating that this is the matched portion of the hostname.
+
+The `HostNameVersioning` scheme can be awkward to use in debug mode as you will typically be accessing a raw IP address such as `127.0.0.1`. There are various online services which you to [access localhost with a custom subdomain][lvh] which you may find helpful in this case.
+
+Hostname based versioning can be particularly useful if you have requirements to route incoming requests to different servers based on the version, as you can configure different DNS records for different API versions.
+
+## QueryParameterVersioning
+
+This scheme is a simple style that includes the version as a query parameter in the URL. For example:
+
+    GET /something/?version=0.1 HTTP/1.1
+    Host: example.com
+    Accept: application/json
+
+---
+
+# Custom versioning schemes
+
+To implement a custom versioning scheme, subclass `BaseVersioning` and override the `.determine_version` method.
+
+## Example
+
+The following example uses a custom `X-API-Version` header to determine the requested version.
+
+    class XAPIVersionScheme(versioning.BaseVersioning):
+        def determine_version(self, request, *args, **kwargs):
+            return request.META.get('HTTP_X_API_VERSION', None)
+
+If your versioning scheme is based on the request URL, you will also want to alter how versioned URLs are determined. In order to do so you should override the `.reverse()` method on the class. See the source code for examples.
+
+[cite]: http://www.slideshare.net/evolve_conference/201308-fielding-evolve/31
+[roy-fielding-on-versioning]: http://www.infoq.com/articles/roy-fielding-on-versioning
+[klabnik-guidelines]: http://blog.steveklabnik.com/posts/2011-07-03-nobody-understands-rest-or-http#i_want_my_api_to_be_versioned
+[heroku-guidelines]: https://github.com/interagent/http-api-design#version-with-accepts-header
+[json-parameters]: http://tools.ietf.org/html/rfc4627#section-6
+[vendor-media-type]: http://en.wikipedia.org/wiki/Internet_media_type#Vendor_tree
+[lvh]: https://reinteractive.net/posts/199-developing-and-testing-rails-applications-with-subdomains

docs/api-guide/views.md

-<a class="github" href="decorators.py"></a> <a class="github" href="views.py"></a>
+source: decorators.py
+        views.py
 
 # Class Based Views
 
@@ -26,7 +27,7 @@ For example:
     class ListUsers(APIView):
         """
         View to list all users in the system.
-        
+
         * Requires token authentication.
         * Only admin users are able to access this view.
         """
@@ -54,7 +55,7 @@ The following attributes control the pluggable aspects of API views.
 
 ### .permission_classes
 
-### .content_negotiation_class 
+### .content_negotiation_class
 
 ## API policy instantiation methods
 
@@ -110,7 +111,7 @@ You won't typically need to override this method.
 
 ### .finalize_response(self, request, response, \*args, **kwargs)
 
-Ensures that any `Response` object returned from the handler method will be rendered into the correct content type, as determined by the content negotation.
+Ensures that any `Response` object returned from the handler method will be rendered into the correct content type, as determined by the content negotiation.
 
 You won't typically need to override this method.
 
@@ -126,19 +127,26 @@ REST framework also allows you to work with regular function based views.  It pr
 
 ## @api_view()
 
-**Signature:** `@api_view(http_method_names)`
+**Signature:** `@api_view(http_method_names=['GET'])`
 
-The core of this functionality is the `api_view` decorator, which takes a list of HTTP methods that your view should respond to.  For example, this is how you would write a very simple view that just manually returns some data:
+The core of this functionality is the `api_view` decorator, which takes a list of HTTP methods that your view should respond to. For example, this is how you would write a very simple view that just manually returns some data:
 
     from rest_framework.decorators import api_view
 
-    @api_view(['GET'])
+    @api_view()
     def hello_world(request):
         return Response({"message": "Hello, world!"})
 
-
 This view will use the default renderers, parsers, authentication classes etc specified in the [settings].
 
+By default only `GET` methods will be accepted. Other methods will respond with "405 Method Not Allowed". To alter this behavior, specify which methods the view allows, like so:
+
+    @api_view(['GET', 'POST'])
+    def hello_world(request):
+        if request.method == 'POST':
+            return Response({"message": "Got some data!", "data": request.data})
+        return Response({"message": "Hello, world!"})
+
 ## API policy decorators
 
 To override the default settings, REST framework provides a set of additional decorators which can be added to your views.  These must come *after* (below) the `@api_view` decorator.  For example, to create a view that uses a [throttle][throttling] to ensure it can only be called once per day by a particular user, use the `@throttle_classes` decorator, passing a list of throttle classes:
@@ -168,5 +176,5 @@ Each of these decorators takes a single argument which must be a list or tuple o
 
 [cite]: http://reinout.vanrees.org/weblog/2011/08/24/class-based-views-usage.html
 [cite2]: http://www.boredomandlaziness.org/2012/05/djangos-cbvs-are-not-mistake-but.html
-[settings]: api-guide/settings.md
-[throttling]: api-guide/throttling.md
+[settings]: settings.md
+[throttling]: throttling.md

docs/api-guide/viewsets.md

-<a class="github" href="viewsets.py"></a>
+source: viewsets.py
 
 # ViewSets
 
@@ -19,6 +19,12 @@ Typically, rather than explicitly registering the views in a viewset in the urlc
 
 Let's define a simple viewset that can be used to list or retrieve all the users in the system.
 
+    from django.contrib.auth.models import User
+    from django.shortcuts import get_object_or_404
+    from myapps.serializers import UserSerializer
+    from rest_framework import viewsets
+    from rest_framework.response import Response
+
     class UserViewSet(viewsets.ViewSet):
         """
         A simple ViewSet that for listing or retrieving users.
@@ -41,6 +47,9 @@ If we need to, we can bind this viewset into two separate views, like so:
 
 Typically we wouldn't do this, but would instead register the viewset with a router, and allow the urlconf to be automatically generated.
 
+    from myapp.views import UserViewSet
+    from rest_framework.routers import DefaultRouter
+
     router = DefaultRouter()
     router.register(r'users', UserViewSet)
     urlpatterns = router.urls
@@ -61,7 +70,7 @@ 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.
 
-## Marking extra methods for routing
+## Marking extra actions 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:
 
@@ -92,14 +101,16 @@ The default routers included with REST framework will provide routes for a stand
         def destroy(self, request, pk=None):
             pass
 
-If you have ad-hoc methods that you need to be routed to, you can mark them as requiring routing using the `@link` or `@action` decorators.  The `@link` decorator will route `GET` requests, and the `@action` decorator will route `POST` requests.
+If you have ad-hoc methods that you need to be routed to, you can mark them as requiring routing using the `@detail_route` or `@list_route` decorators.
+
+The `@detail_route` decorator contains `pk` in its URL pattern and is intended for methods which require a single instance. The `@list_route` decorator is intended for methods which operate on a list of objects.
 
 For example:
 
     from django.contrib.auth.models import User
-    from rest_framework import viewsets
     from rest_framework import status
-    from rest_framework.decorators import action
+    from rest_framework import viewsets
+    from rest_framework.decorators import detail_route, list_route
     from rest_framework.response import Response
     from myapp.serializers import UserSerializer, PasswordSerializer
 
@@ -110,10 +121,10 @@ For example:
         queryset = User.objects.all()
         serializer_class = UserSerializer
 
-        @action()
+        @detail_route(methods=['post'])
         def set_password(self, request, pk=None):
             user = self.get_object()
-            serializer = PasswordSerializer(data=request.DATA)
+            serializer = PasswordSerializer(data=request.data)
             if serializer.is_valid():
                 user.set_password(serializer.data['password'])
                 user.save()
@@ -122,17 +133,27 @@ For example:
                 return Response(serializer.errors,
                                 status=status.HTTP_400_BAD_REQUEST)
 
-The `@action` and `@link` decorators can additionally take extra arguments that will be set for the routed view only.  For example...
+        @list_route()
+        def recent_users(self, request):
+            recent_users = User.objects.all().order('-last_login')
+            page = self.paginate_queryset(recent_users)
+            serializer = self.get_pagination_serializer(page)
+            return Response(serializer.data)
+
+The decorators can additionally take extra arguments that will be set for the routed view only.  For example...
 
-        @action(permission_classes=[IsAdminOrIsSelf])
+        @detail_route(methods=['post'], permission_classes=[IsAdminOrIsSelf])
         def set_password(self, request, pk=None):
            ...
 
-The `@action` decorator will route `POST` requests by default, but may also accept other HTTP methods, by using the `method` argument.  For example:
+These decorators will route `GET` requests by default, but may also accept other HTTP methods, by using the `methods` argument.  For example:
 
-        @action(methods=['POST', 'DELETE'])
+        @detail_route(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/$`
+
 ---
 
 # API Reference
@@ -180,6 +201,8 @@ Note that you can use any of the standard attributes or method overrides provide
         def get_queryset(self):
             return self.request.user.accounts.all()
 
+Note however that upon removal of the `queryset` property from your `ViewSet`, any associated [router][routers] will be unable to derive the base_name of your Model automatically, and so you will have to specify the `base_name` kwarg as part of your [router registration][routers].
+
 Also note that although this class provides the complete set of create/list/retrieve/update/destroy actions by default, you can restrict the available operations by using the standard permission classes.
 
 ## ReadOnlyModelViewSet
@@ -212,7 +235,7 @@ To create a base viewset class that provides `create`, `list` and `retrieve` ope
                                     mixins.RetrieveModelMixin,
                                     viewsets.GenericViewSet):
         """
-        A viewset that provides `retrieve`, `update`, and `list` actions.
+        A viewset that provides `retrieve`, `create`, and `list` actions.
 
         To use it, override the class and set the `.queryset` and
         `.serializer_class` attributes.
@@ -222,3 +245,4 @@ To create a base viewset class that provides `create`, `list` and `retrieve` ope
 By creating your own base `ViewSet` classes, you can provide common behavior that can be reused in multiple viewsets across your API.
 
 [cite]: http://guides.rubyonrails.org/routing.html
+[routers]: routers.md