version the api (bug 852233)

Andy McKay · Andy McKay · commit 81a09554d645 · 2013-04-02T14:17:13.000-07:00
diff --git a/docs/topics/api.rst b/docs/topics/api.rst
@@ -17,6 +17,31 @@ This API is for Apps. There is a separate set of `APIs for Add-ons`_.
    api/reviewers.rst
    api/ratings.rst
 
+Versioning
+==========
+
+This API is versioned and we are currently moving towards version 1 of the API.
+The API will be versioned by the URL, so that version 1 APIs will all be at::
+
+    /api/v1/...
+
+If you are not using the most recent version of the API then you will get
+a header in the response::
+
+    X-API-Status: Deprecated
+
+The current policy for how long deprecated APIs will exist has not been
+defined, but it would include time for any clients to upgrade before versions
+are turned off.
+
+We will also return the version of the API we think you are using::
+
+    X-API-Version: 1
+
+.. note: Before v1 is released, the API was unversioned at `/api/`, because of
+the small number of clients using that URL, we hope all users are able to
+update to `/api/v1/` quickly so we can remove that unversioned URL.
+
 Authentication
 ==============
 
@@ -135,7 +160,6 @@ Verbs
 This follows the order of the `django-tastypie`_ REST verbs, a PUT for an
 update and POST for create.
 
-
 Responses
 =========
 
diff --git a/mkt/api/middleware.py b/mkt/api/middleware.py
@@ -1,3 +1,5 @@
+import re
+
 from django.conf import settings
 from django.middleware.transaction import TransactionMiddleware
 
@@ -51,12 +53,12 @@ def process_response(self, request, response):
         # hook for figuring out if a response should have the CORS headers on
         # it. That's because it will often error out with immediate HTTP
         # responses.
-
-        fireplacey = request.META.get('HTTP_ORIGIN') == settings.FIREPLACE_URL
+        fireplace_url = settings.FIREPLACE_URL
+        fireplacey = request.META.get('HTTP_ORIGIN') == fireplace_url
         if fireplacey or getattr(request, 'CORS', None):
             # If this is a request from our hosted frontend, allow cookies.
             if fireplacey:
-                response['Access-Control-Allow-Origin'] = settings.FIREPLACE_URL
+                response['Access-Control-Allow-Origin'] = fireplace_url
                 response['Access-Control-Allow-Credentials'] = 'true'
             else:
                 response['Access-Control-Allow-Origin'] = '*'
@@ -69,3 +71,32 @@ def process_response(self, request, response):
                 response['Access-Control-Allow-Headers'] = 'Content-Type'
             response['Access-Control-Allow-Methods'] = ', '.join(options)
         return response
+
+v_re = re.compile('^/api/v(?P<version>\d+)/|^/api/')
+
+
+class APIVersionMiddleware(object):
+    """
+    Figures out what version of the API they are on. Maybe adds in a
+    deprecation notice.
+    """
+
+    def process_request(self, request):
+        try:
+            version = v_re.match(request.META['PATH_INFO']).group('version')
+        except AttributeError:
+            # Not in the API.
+            return
+
+        # If you are in the API, but don't have a version, this will be None.
+        request.API_VERSION = version
+
+    def process_response(self, request, response):
+        # Not in the API.
+        if not hasattr(request, 'API_VERSION'):
+            return response
+
+        response['X-API-Version'] = request.API_VERSION
+        if not request.API_VERSION:
+            response['X-API-Status'] = 'Deprecated'
+        return response
diff --git a/mkt/api/tests/test_middleware.py b/mkt/api/tests/test_middleware.py
@@ -8,7 +8,7 @@
 
 import amo.tests
 from mkt.api.middleware import (APIPinningMiddleware, APITransactionMiddleware,
-                                CORSMiddleware)
+                                APIVersionMiddleware, CORSMiddleware)
 from mkt.site.middleware import RedirectPrefixedURIMiddleware
 
 fireplace_url = 'http://firepla.ce:1234'
@@ -94,3 +94,22 @@ def test_not_pinned(self):
         self.req.amo_user.is_anonymous.return_value = True
         self.pin.process_request(self.req)
         ok_(not this_thread_is_pinned())
+
+
+class TestAPIVersionMiddleware(amo.tests.TestCase):
+
+    def setUp(self):
+        self.dep = APIVersionMiddleware()
+
+    def req(self, url, header):
+        req = RequestFactory().get(url)
+        self.dep.process_request(req)
+        res = self.dep.process_response(req, HttpResponse())
+        return res.get(header, None)
+
+    def test_notice(self):
+        eq_(self.req('/foo/', 'X-API-Status'), None)
+        eq_(self.req('/foo/api/', 'X-API-Status'), None)
+        eq_(self.req('/api/', 'X-API-Status'), 'Deprecated')
+        eq_(self.req('/api/v1/', 'X-API-Status'), None)
+        eq_(self.req('/api/v1/', 'X-API-Version'), '1')
diff --git a/mkt/settings.py b/mkt/settings.py
@@ -97,6 +97,7 @@
     'mkt.fragments.middleware.VaryOnAJAXMiddleware',
     'mkt.site.middleware.DeviceDetectionMiddleware',
     'mkt.fragments.middleware.HijackRedirectMiddleware',
+    'mkt.api.middleware.APIVersionMiddleware',
     'mkt.api.middleware.CORSMiddleware',
     'mkt.api.middleware.APITransactionMiddleware',
     'mkt.api.middleware.APIPinningMiddleware'
diff --git a/mkt/urls.py b/mkt/urls.py
@@ -28,6 +28,15 @@
 handler404 = 'mkt.site.views.handler404'
 handler500 = 'mkt.site.views.handler500'
 
+api_patterns = patterns('',
+    url('', include(home_api_patterns)),
+    url('', include('mkt.api.urls')),
+    url('', include(account_api_patterns)),
+    url('', include(reviewer_api_patterns)),
+    url('', include('mkt.webpay.urls')),
+    url('', include(receipt_api_patterns)),
+    url('', include('mkt.monolith.urls')),
+)
 
 urlpatterns = patterns('',
     # Home.
@@ -118,13 +127,9 @@
     url('^login$', login, name='users.login'),
     url('^logout$', logout, name='users.logout'),
 
-    url('^api/', include(home_api_patterns)),
-    url('^api/', include('mkt.api.urls')),
-    url('^api/', include(account_api_patterns)),
-    url('^api/', include(reviewer_api_patterns)),
-    url('^api/', include('mkt.webpay.urls')),
-    url('^api/', include(receipt_api_patterns)),
-    url('^api/', include('mkt.monolith.urls')),
+    # Version the API here.
+    url('^api/v1/', include(api_patterns)),
+    url('^api/', include(api_patterns)),
 
     url('^appcache/', include('django_appcache.urls')),
 
