feat(controller): check client against API version

Before locking the API version, we needed some way to ensure that
we did not break the client. This was done by comparing the client's
version against the server. If there was a mismatch on the minor or
major release versions (as noted in Semver 2.0.0[1]), the server
would refuse the request. Because we have locked the API version,
it would make sense to test against that to see if the client is
compatible with the API. If not, then the client should upgrade.

This also modifies the current behaviour to warn the user on a minor
version mismatch. If there is a minor version mismatch between the
client and the server, it will press onwards and display a warning,
advising the user to upgrade. If there is a major version mismatch,
then the API server will refuse the request as before.

[1]: http://semver.org/

Author: Matthew Fisher

client/deis.py

@@ -70,6 +70,9 @@
 
 __version__ = '1.1.0-dev'
 
+# what version of the API is this client compatible with?
+__api_version__ = '1.0'
+
 
 locale.setlocale(locale.LC_ALL, '')
 
@@ -392,10 +395,18 @@ def _dispatch(self, method, path, body=None, **kwargs):
         url = urlparse.urljoin(controller, path, **kwargs)
         headers = {
             'content-type': 'application/json',
-            'X-Deis-Version': __version__.rsplit('.', 1)[0],
+            'X-Deis-Version': __api_version__.rsplit('.', 1)[0],
             'Authorization': 'token {}'.format(token)
         }
         response = func(url, data=body, headers=headers)
+        # check for version mismatch
+        server_api_version = response.headers.get('X_DEIS_API_VERSION')
+        if server_api_version is not None and server_api_version != __api_version__:
+            self._logger.warning("""
+ !    WARNING: Client and server API versions do not match. Please consider upgrading.
+ !    Client version: {}
+ !    Server version: {}
+""".format(__api_version__, server_api_version))
         return response
 
     def apps(self, args):

controller/api/__init__.py

@@ -1,3 +1,5 @@
 """
 The **api** Django app presents a RESTful web API for interacting with the **deis** system.
 """
+
+__version__ = '1.0.0'

controller/api/middleware.py

@@ -3,16 +3,16 @@
 from django.http import HttpResponse
 from rest_framework import status
 
-from deis import __version__
+from api import __version__
 
 
 class VersionMiddleware:
 
     def process_request(self, request):
         try:
-            # server and client version must match "x.y"
+            # server and client version must match the major release point
             client_version = request.META['HTTP_X_DEIS_VERSION']
-            server_version = __version__.rsplit('.', 1)[0]
+            server_version = __version__.rsplit('.', 2)[0]
             if client_version != server_version:
                 message = {
                     'error': 'Client and server versions do not match. ' +
@@ -26,3 +26,8 @@ def process_request(self, request):
                 )
         except KeyError:
             pass
+
+    def process_response(self, request, response):
+        # clients shouldn't care about the patch release
+        response['X_DEIS_API_VERSION'] = __version__.rsplit('.', 1)[0]
+        return response

controller/api/tests/test_api_middleware.py

@@ -9,7 +9,7 @@
 from django.test import TestCase
 from rest_framework.authtoken.models import Token
 
-from deis import __version__
+from api import __version__
 
 
 class APIMiddlewareTest(TestCase):
@@ -28,10 +28,12 @@ def test_x_deis_version_header_good(self):
         """
         response = self.client.get(
             '/v1/apps',
-            HTTP_X_DEIS_VERSION=__version__.rsplit('.', 1)[0],
+            HTTP_X_DEIS_VERSION=__version__.rsplit('.', 2)[0],
             HTTP_AUTHORIZATION='token {}'.format(self.token),
         )
         self.assertEqual(response.status_code, 200)
+        self.assertEqual(response.has_header('X_DEIS_API_VERSION'), True)
+        self.assertEqual(response['X_DEIS_API_VERSION'], __version__.rsplit('.', 1)[0])
 
     def test_x_deis_version_header_bad(self):
         """