More docs, plus 'ALLOWED_VERSIONS' setting.

docs/api-guide/exceptions.md

@@ -128,6 +128,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)`
@@ -136,6 +144,14 @@ 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)`

docs/api-guide/settings.md

@@ -166,6 +166,28 @@ Default: `ordering`
 
 ---
 
+## Versioning settings
+
+#### DEFAULT_VERSION
+
+The value that should be used for `request.version` when no versioning information is present.
+
+Default: `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.
+
+Default: `None`
+
+#### VERSION_PARAMETER
+
+The string that should used for any versioning parameters, such as in the media type or URL query parameters.
+
+Default: `'version'`
+
+---
+
 ## Authentication settings
 
 *The following settings control the behavior of unauthenticated requests.*

docs/api-guide/versioning.md

@@ -6,4 +6,197 @@ source: versioning.py
 > 
 > — [Roy Fielding][cite].
 
-[cite]: http://www.slideshare.net/evolve_conference/201308-fielding-evolve/31
+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.
+
+## 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 `NaemspaceVersioning` 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
+[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/index.md

@@ -175,6 +175,7 @@ The API guide is your complete reference manual to all the functionality provide
 * [Throttling][throttling]
 * [Filtering][filtering]
 * [Pagination][pagination]
+* [Versioning][versioning]
 * [Content negotiation][contentnegotiation]
 * [Format suffixes][formatsuffixes]
 * [Returning URLs][reverse]
@@ -294,6 +295,7 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 [throttling]: api-guide/throttling.md
 [filtering]: api-guide/filtering.md
 [pagination]: api-guide/pagination.md
+[versioning]: api-guide/versioning.md
 [contentnegotiation]: api-guide/content-negotiation.md
 [formatsuffixes]: api-guide/format-suffixes.md
 [reverse]: api-guide/reverse.md

mkdocs.yml

@@ -32,6 +32,7 @@ pages:
  - ['api-guide/throttling.md', 'API Guide', 'Throttling']
  - ['api-guide/filtering.md', 'API Guide', 'Filtering']
  - ['api-guide/pagination.md', 'API Guide', 'Pagination']
+ - ['api-guide/versioning.md', 'API Guide', 'Versioning']
  - ['api-guide/content-negotiation.md', 'API Guide', 'Content negotiation']
  - ['api-guide/format-suffixes.md', 'API Guide', 'Format suffixes']
  - ['api-guide/reverse.md', 'API Guide', 'Returning URLs']

rest_framework/exceptions.py

@@ -89,6 +89,11 @@ class PermissionDenied(APIException):
     default_detail = _('You do not have permission to perform this action.')
 
 
+class NotFound(APIException):
+    status_code = status.HTTP_404_NOT_FOUND
+    default_detail = _('Not found')
+
+
 class MethodNotAllowed(APIException):
     status_code = status.HTTP_405_METHOD_NOT_ALLOWED
     default_detail = _("Method '%s' not allowed.")

rest_framework/settings.py

@@ -68,6 +68,11 @@ DEFAULTS = {
     'SEARCH_PARAM': 'search',
     'ORDERING_PARAM': 'ordering',
 
+    # Versioning
+    'DEFAULT_VERSION': None,
+    'ALLOWED_VERSIONS': None,
+    'VERSION_PARAM': 'version',
+
     # Authentication
     'UNAUTHENTICATED_USER': 'django.contrib.auth.models.AnonymousUser',
     'UNAUTHENTICATED_TOKEN': None,

rest_framework/versioning.py

@@ -1,13 +1,20 @@
 # coding: utf-8
 from __future__ import unicode_literals
+from django.utils.translation import ugettext_lazy as _
+from rest_framework import exceptions
 from rest_framework.compat import unicode_http_header
 from rest_framework.reverse import _reverse
+from rest_framework.settings import api_settings
 from rest_framework.templatetags.rest_framework import replace_query_param
 from rest_framework.utils.mediatypes import _MediaType
 import re
 
 
 class BaseVersioning(object):
+    default_version = api_settings.DEFAULT_VERSION
+    allowed_versions = api_settings.ALLOWED_VERSIONS
+    version_param = api_settings.VERSION_PARAM
+
     def determine_version(self, request, *args, **kwargs):
         msg = '{cls}.determine_version() must be implemented.'
         raise NotImplemented(msg.format(
@@ -17,46 +24,10 @@ class BaseVersioning(object):
     def reverse(self, viewname, args=None, kwargs=None, request=None, format=None, **extra):
         return _reverse(viewname, args, kwargs, request, format, **extra)
 
-
-class QueryParameterVersioning(BaseVersioning):
-    """
-    GET /something/?version=0.1 HTTP/1.1
-    Host: example.com
-    Accept: application/json
-    """
-    default_version = None
-    version_param = 'version'
-
-    def determine_version(self, request, *args, **kwargs):
-        return request.query_params.get(self.version_param)
-
-    def reverse(self, viewname, args=None, kwargs=None, request=None, format=None, **extra):
-        url = super(QueryParameterVersioning, self).reverse(
-            viewname, args, kwargs, request, format, **extra
-        )
-        if request.version is not None:
-            return replace_query_param(url, self.version_param, request.version)
-        return url
-
-
-class HostNameVersioning(BaseVersioning):
-    """
-    GET /something/ HTTP/1.1
-    Host: v1.example.com
-    Accept: application/json
-    """
-    default_version = None
-    hostname_regex = re.compile(r'^([a-zA-Z0-9]+)\.[a-zA-Z0-9]+\.[a-zA-Z0-9]+$')
-
-    def determine_version(self, request, *args, **kwargs):
-        hostname, seperator, port = request.get_host().partition(':')
-        match = self.hostname_regex.match(hostname)
-        if not match:
-            return self.default_version
-        return match.group(1)
-
-    # We don't need to implement `reverse`, as the hostname will already be
-    # preserved as part of the REST framework `reverse` implementation.
+    def is_allowed_version(self, version):
+        if not self.allowed_versions:
+            return True
+        return (version == self.default_version) or (version in self.allowed_versions)
 
 
 class AcceptHeaderVersioning(BaseVersioning):
@@ -65,13 +36,15 @@ class AcceptHeaderVersioning(BaseVersioning):
     Host: example.com
     Accept: application/json; version=1.0
     """
-    default_version = None
-    version_param = 'version'
+    invalid_version_message = _("Invalid version in 'Accept' header.")
 
     def determine_version(self, request, *args, **kwargs):
         media_type = _MediaType(request.accepted_media_type)
         version = media_type.params.get(self.version_param, self.default_version)
-        return unicode_http_header(version)
+        version = unicode_http_header(version)
+        if not self.is_allowed_version(version):
+            raise exceptions.NotAcceptable(self.invalid_version_message)
+        return version
 
     # We don't need to implement `reverse`, as the versioning is based
     # on the `Accept` header, not on the request URL.
@@ -94,11 +67,13 @@ class URLPathVersioning(BaseVersioning):
     Host: example.com
     Accept: application/json
     """
-    default_version = None
-    version_param = 'version'
+    invalid_version_message = _('Invalid version in URL path.')
 
     def determine_version(self, request, *args, **kwargs):
-        return kwargs.get(self.version_param, self.default_version)
+        version = kwargs.get(self.version_param, self.default_version)
+        if not self.is_allowed_version(version):
+            raise exceptions.NotFound(self.invalid_version_message)
+        return version
 
     def reverse(self, viewname, args=None, kwargs=None, request=None, format=None, **extra):
         if request.version is not None:
@@ -134,13 +109,16 @@ class NamespaceVersioning(BaseVersioning):
     Host: example.com
     Accept: application/json
     """
-    default_version = None
+    invalid_version_message = _('Invalid version in URL path.')
 
     def determine_version(self, request, *args, **kwargs):
         resolver_match = getattr(request, 'resolver_match', None)
         if (resolver_match is None or not resolver_match.namespace):
             return self.default_version
-        return resolver_match.namespace
+        version = resolver_match.namespace
+        if not self.is_allowed_version(version):
+            raise exceptions.NotFound(self.invalid_version_message)
+        return version
 
     def reverse(self, viewname, args=None, kwargs=None, request=None, format=None, **extra):
         if request.version is not None:
@@ -148,3 +126,49 @@ class NamespaceVersioning(BaseVersioning):
         return super(NamespaceVersioning, self).reverse(
             viewname, args, kwargs, request, format, **extra
         )
+
+
+class HostNameVersioning(BaseVersioning):
+    """
+    GET /something/ HTTP/1.1
+    Host: v1.example.com
+    Accept: application/json
+    """
+    hostname_regex = re.compile(r'^([a-zA-Z0-9]+)\.[a-zA-Z0-9]+\.[a-zA-Z0-9]+$')
+    invalid_version_message = _('Invalid version in hostname.')
+
+    def determine_version(self, request, *args, **kwargs):
+        hostname, seperator, port = request.get_host().partition(':')
+        match = self.hostname_regex.match(hostname)
+        if not match:
+            return self.default_version
+        version = match.group(1)
+        if not self.is_allowed_version(version):
+            raise exceptions.NotFound(self.invalid_version_message)
+        return version
+
+    # We don't need to implement `reverse`, as the hostname will already be
+    # preserved as part of the REST framework `reverse` implementation.
+
+
+class QueryParameterVersioning(BaseVersioning):
+    """
+    GET /something/?version=0.1 HTTP/1.1
+    Host: example.com
+    Accept: application/json
+    """
+    invalid_version_message = _('Invalid version in query parameter.')
+
+    def determine_version(self, request, *args, **kwargs):
+        version = request.query_params.get(self.version_param)
+        if not self.is_allowed_version(version):
+            raise exceptions.NotFound(self.invalid_version_message)
+        return version
+
+    def reverse(self, viewname, args=None, kwargs=None, request=None, format=None, **extra):
+        url = super(QueryParameterVersioning, self).reverse(
+            viewname, args, kwargs, request, format, **extra
+        )
+        if request.version is not None:
+            return replace_query_param(url, self.version_param, request.version)
+        return url

tests/test_versioning.py

@@ -1,5 +1,5 @@
 from django.conf.urls import include, url
-from rest_framework import versioning
+from rest_framework import status, versioning
 from rest_framework.decorators import APIView
 from rest_framework.response import Response
 from rest_framework.reverse import reverse
@@ -16,6 +16,16 @@ class ReverseView(APIView):
         return Response({'url': reverse('another', request=request)})
 
 
+class RequestInvalidVersionView(APIView):
+    def determine_version(self, request, *args, **kwargs):
+        scheme = self.versioning_class()
+        scheme.allowed_versions = ('v1', 'v2')
+        return (scheme.determine_version(request, *args, **kwargs), scheme)
+
+    def get(self, request, *args, **kwargs):
+        return Response({'version': request.version})
+
+
 factory = APIRequestFactory()
 
 mock_view = lambda request: None
@@ -150,7 +160,7 @@ class TestURLReversing(APITestCase):
         response = view(request)
         assert response.data == {'url': 'http://testserver/another/'}
 
-    def test_namespace_versioning(self):
+    def test_reverse_namespace_versioning(self):
         class FakeResolverMatch:
             namespace = 'v1'
 
@@ -165,3 +175,49 @@ class TestURLReversing(APITestCase):
         request = factory.get('/endpoint/')
         response = view(request)
         assert response.data == {'url': 'http://testserver/another/'}
+
+
+class TestInvalidVersion:
+    def test_invalid_query_param_versioning(self):
+        scheme = versioning.QueryParameterVersioning
+        view = RequestInvalidVersionView.as_view(versioning_class=scheme)
+
+        request = factory.get('/endpoint/?version=v3')
+        response = view(request)
+        assert response.status_code == status.HTTP_404_NOT_FOUND
+
+    def test_invalid_host_name_versioning(self):
+        scheme = versioning.HostNameVersioning
+        view = RequestInvalidVersionView.as_view(versioning_class=scheme)
+
+        request = factory.get('/endpoint/', HTTP_HOST='v3.example.org')
+        response = view(request)
+        assert response.status_code == status.HTTP_404_NOT_FOUND
+
+    def test_invalid_accept_header_versioning(self):
+        scheme = versioning.AcceptHeaderVersioning
+        view = RequestInvalidVersionView.as_view(versioning_class=scheme)
+
+        request = factory.get('/endpoint/', HTTP_ACCEPT='application/json; version=v3')
+        response = view(request)
+        assert response.status_code == status.HTTP_406_NOT_ACCEPTABLE
+
+    def test_invalid_url_path_versioning(self):
+        scheme = versioning.URLPathVersioning
+        view = RequestInvalidVersionView.as_view(versioning_class=scheme)
+
+        request = factory.get('/v3/endpoint/')
+        response = view(request, version='v3')
+        assert response.status_code == status.HTTP_404_NOT_FOUND
+
+    def test_invalid_namespace_versioning(self):
+        class FakeResolverMatch:
+            namespace = 'v3'
+
+        scheme = versioning.NamespaceVersioning
+        view = RequestInvalidVersionView.as_view(versioning_class=scheme)
+
+        request = factory.get('/v3/endpoint/')
+        request.resolver_match = FakeResolverMatch
+        response = view(request, version='v3')
+        assert response.status_code == status.HTTP_404_NOT_FOUND