API: accept X-RTD-Hosting-Integrations-API-Version

This new header will force the API endpoint to return a specific JSON version
schema without taking into consideration the any other header.

The idea behind this is to allow theme authors guarrantees about the JSON scheme
they are expecting; without stopping us to move forward with potential changes
required to the API response when adding new features/addons/etc.

Related readthedocs/addons#64

Author: humitos

readthedocs/proxito/tests/responses/v0.json

@@ -1,4 +1,5 @@
 {
+  "api_version": 0,
   "comment": "THIS RESPONSE IS IN ALPHA FOR TEST PURPOSES ONLY AND IT'S GOING TO CHANGE COMPLETELY -- DO NOT USE IT!",
   "projects": {
     "current": {

readthedocs/proxito/tests/responses/v1.json

@@ -1,3 +1,4 @@
 {
+    "api_version": "1",
     "comment": "Undefined yet. Use v0 for now"
 }

readthedocs/proxito/tests/test_hosting.py

@@ -111,3 +111,15 @@ def test_get_config_unsupported_version(self):
         )
         assert r.status_code == 400
         assert r.json() == self._get_response_dict("v2")
+
+    def test_get_config_explicit_api_version(self):
+        r = self.client.get(
+            reverse("proxito_readthedocs_config_json"),
+            {"url": "https://project.dev.readthedocs.io/en/latest/"},
+            secure=True,
+            HTTP_HOST="project.dev.readthedocs.io",
+            HTTP_X_RTD_HOSTING_INTEGRATIONS_VERSION="0.1.0",
+            HTTP_X_RTD_HOSTING_INTEGRATIONS_API_VERSION="1",
+        )
+        assert r.status_code == 200
+        assert r.json() == self._get_response_dict("v1")

readthedocs/proxito/views/hosting.py

@@ -23,10 +23,14 @@
 
 class ClientError(Exception):
     VERSION_NOT_CURRENTLY_SUPPORTED = (
-        "The version specified in 'X-RTD-Hosting-Integrations-Version'"
-        " is currently not supported"
+        "The version specified in 'X-RTD-Hosting-Integrations-Version' "
+        "or 'X-RTD-Hosting-Integrations-API-Version' "
+        "is currently not supported"
+    )
+    VERSION_INVALID = (
+        "'X-RTD-Hosting-Integrations-Version' or 'X-RTD-Hosting-Integrations-API-Version' "
+        "header version is invalid"
     )
-    VERSION_INVALID = "'X-RTD-Hosting-Integrations-Version' header version is invalid"
     VERSION_HEADER_MISSING = (
         "'X-RTD-Hosting-Integrations-Version' header attribute is required"
     )
@@ -44,6 +48,16 @@ class ReadTheDocsConfigJson(CDNCacheControlMixin, View):
 
       url (required): absolute URL from where the request is performed
         (e.g. ``window.location.href``)
+
+    Headers:
+
+      X-RTD-Hosting-Integrations-Version (required): javascript client version.
+        It's used by the endpoint to decide what's the JSON structure compatible with the client
+        (e.g. ``1.0.2``)
+
+      X-RTD-Hosting-Integrations-API-Version (optional): force the endpoint to return a specific
+        JSON structure in particular. Used by theme authors to keep compatibility with
+        their integration (e.g. ``1``)
     """
 
     def get(self, request):
@@ -63,10 +77,22 @@ def get(self, request):
                 },
                 status=400,
             )
+
+        addons_version_explicit = request.headers.get(
+            "X-RTD-Hosting-Integrations-API-Version"
+        )
         try:
             addons_version = packaging.version.parse(addons_version)
             if addons_version.major not in ADDONS_VERSIONS_SUPPORTED:
                 raise ClientError
+
+            if addons_version_explicit:
+                addons_version_explicit = packaging.version.parse(
+                    addons_version_explicit
+                )
+                if addons_version_explicit.major not in ADDONS_VERSIONS_SUPPORTED:
+                    raise ClientError
+
         except packaging.version.InvalidVersion:
             return JsonResponse(
                 {
@@ -90,7 +116,13 @@ def get(self, request):
         project.get_default_version()
         build = version.builds.last()
 
-        data = AddonsResponse().get(addons_version, project, version, build, filename)
+        data = AddonsResponse().get(
+            addons_version_explicit or addons_version,
+            project,
+            version,
+            build,
+            filename,
+        )
         return JsonResponse(data, json_dumps_params=dict(indent=4))
 
 
@@ -160,6 +192,7 @@ def _v0(self, project, version, build, filename):
         """
 
         data = {
+            "api_version": "0",
             "comment": (
                 "THIS RESPONSE IS IN ALPHA FOR TEST PURPOSES ONLY"
                 " AND IT'S GOING TO CHANGE COMPLETELY -- DO NOT USE IT!"
@@ -270,5 +303,6 @@ def _v0(self, project, version, build, filename):
 
     def _v1(self, project, version, build, filename):
         return {
+            "api_version": "1",
             "comment": "Undefined yet. Use v0 for now",
         }