API: use <meta> to define supported API version

humitos · humitos · commit f3eaa7a33c51 · 2023-04-27T13:17:32.000-06:00
Let users to define `<meta name="readthedocs-api-version" content="1.0">` to tell Read the Docs client what is the API scheme version supported by them. When our client request the API data, if the `api_version` returned does not match with the one expected by the user, another request is done to force a particular API scheme version. Then, we dispatch a `readthedocsdataready` custom event and expose `window.readthedocs`, to let our users know this data is ready to be consumed by their own integrations. Closes #60 Closes #61
diff --git a/public/index.html b/public/index.html
@@ -1,6 +1,13 @@
 <html>
   <head>
+    <meta name="readthedocs-api-version" content="1">
     <title>Documentation Addons - Read the Docs</title>
+    <script>
+        // Example of using "readthedocsdataready" with a different API version supported
+        document.addEventListener("readthedocsdataready", function(event) {
+          console.debug(event.detail);
+        });
+    </script>
   </head>
   <body>
 
diff --git a/src/readthedocs-config.js b/src/readthedocs-config.js
@@ -1,5 +1,17 @@
 import { CLIENT_VERSION } from "./utils";
 
+/**
+ * Get the Read the Docs API version supported by user's integrations.
+ *
+ */
+function _getMetadataAPIVersion() {
+  const meta = document.querySelector("meta[name=readthedocs-api-version]");
+  if (meta !== undefined) {
+    return meta.getAttribute("content");
+  }
+  return undefined;
+}
+
 /**
  * Load Read the Docs configuration from API endpoint.
  *
@@ -19,11 +31,56 @@ export function getReadTheDocsConfig() {
   return fetch(url, {
     method: "GET",
     headers: { "X-RTD-Hosting-Integrations-Version": CLIENT_VERSION },
-  }).then((response) => {
-    if (!response.ok) {
-      console.debug("Error parsing configuration data");
-      return undefined;
-    }
-    return response.json();
-  });
+  })
+    .then((response) => {
+      if (!response.ok) {
+        console.debug("Error parsing configuration data");
+        return undefined;
+      }
+      return response.json();
+    })
+    .then((data) => {
+      // We force the user to define the `<meta>` tag to be able to use Read the Docs data directly.
+      // This is to keep forward/backward compatibility without breaking integrations.
+      const metadataAPIVersion = _getMetadataAPIVersion();
+      if (metadataAPIVersion !== undefined) {
+        if (metadataAPIVersion !== data.api_version) {
+          // When the API scheme version returned doesn't match the one defined via `<meta>` tag by the user,
+          // we perform another request to get the Read the Docs response in the structure
+          // that's supported by the user and dispatch a custom event letting them know
+          // this data is ready to be consumed under `event.detail` or `window.readthedocs`.
+          fetch(url, {
+            method: "GET",
+            headers: {
+              "X-RTD-Hosting-Integrations-Version": CLIENT_VERSION,
+              "X-RTD-Hosting-Integrations-API-Version": metadataAPIVersion,
+            },
+          })
+            .then((response) => {
+              if (!response.ok) {
+                console.debug("Error parsing configuration data");
+                return undefined;
+              }
+              return response.json();
+            })
+            .then((data) => {
+              const readthedocsDataReady = new CustomEvent(
+                "readthedocsdataready",
+                { detail: data }
+              );
+              window.readthedocs = data;
+              document.dispatchEvent(readthedocsDataReady);
+              return undefined;
+            });
+        } else {
+          const readthedocsDataReady = new CustomEvent("readthedocsdataready", {
+            detail: data,
+          });
+          window.readthedocs = data;
+          document.dispatchEvent(readthedocsDataReady);
+        }
+      }
+
+      return data;
+    });
 }
