From 068fdbd3f9e44d99ee934cea9b1c30f055f968dc Mon Sep 17 00:00:00 2001
From: jonaswinkler <17569239+jonaswinkler@users.noreply.github.com>
Date: Fri, 26 Feb 2021 11:13:28 +0100
Subject: [PATCH] added versioning headers to the API

---
 docs/api.rst                | 13 +++++++++++++
 src/paperless/middleware.py | 18 ++++++++++++++++++
 src/paperless/settings.py   |  3 +++
 3 files changed, 34 insertions(+)
 create mode 100644 src/paperless/middleware.py

diff --git a/docs/api.rst b/docs/api.rst
index ec24aca7c..d34558b36 100644
--- a/docs/api.rst
+++ b/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
 =============
 
diff --git a/src/paperless/middleware.py b/src/paperless/middleware.py
new file mode 100644
index 000000000..0fe526556
--- /dev/null
+++ b/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
diff --git a/src/paperless/settings.py b/src/paperless/settings.py
index 3dcff4a89..1e864cb34 100644
--- a/src/paperless/settings.py
+++ b/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',