added versioning headers to the API

docs/api.rst

@@ -305,6 +305,19 @@ API versions are specified by submitting an additional HTTP ``Accept`` header wi
 If an invalid version is specified, Paperless 1.3.0 will respond with "406 Not Acceptable" and an error message in the body.
 Earlier versions of Paperless will serve API version 1 regardless of whether a version is specified via the ``Accept`` header.
 
+If a client wishes to verify whether it is compatible with any given server, the following procedure should be performed:
+
+1.  Perform an *authenticated* request against any API endpoint. If the server is on version 1.3.0 or newer, the server will
+    add two custom headers to the response:
+
+    .. code::
+
+        X-Api-Version: 2
+        X-Version: 1.3.0
+
+2.  Determine whether the client is compatible with this server based on the presence/absence of these headers and their values if present.
+
+
 API Changelog
 =============
 

src/paperless/middleware.py

@@ -0,0 +1,18 @@
+from django.conf import settings
+
+from paperless import version
+
+
+class ApiVersionMiddleware:
+
+    def __init__(self, get_response):
+        self.get_response = get_response
+
+    def __call__(self, request):
+        response = self.get_response(request)
+        if request.user.is_authenticated:
+            versions = settings.REST_FRAMEWORK['ALLOWED_VERSIONS']
+            response['X-Api-Version'] = versions[len(versions)-1]
+            response['X-Version'] = ".".join([str(_) for _ in version.__version__])
+
+        return response

src/paperless/settings.py

@@ -115,6 +115,8 @@ REST_FRAMEWORK = {
     ],
     'DEFAULT_VERSIONING_CLASS': 'rest_framework.versioning.AcceptHeaderVersioning',
     'DEFAULT_VERSION': '1',
+    # Make sure these are ordered and that the most recent version appears
+    # last
     'ALLOWED_VERSIONS': ['1', '2']
 }
 
@@ -131,6 +133,7 @@ MIDDLEWARE = [
     'django.middleware.locale.LocaleMiddleware',
     'django.middleware.common.CommonMiddleware',
     'django.middleware.csrf.CsrfViewMiddleware',
+    'paperless.middleware.ApiVersionMiddleware',
     'django.contrib.auth.middleware.AuthenticationMiddleware',
     'django.contrib.messages.middleware.MessageMiddleware',
     'django.middleware.clickjacking.XFrameOptionsMiddleware',