From 2c27001128af44a4ae94f0a064bd3cbd7a894912 Mon Sep 17 00:00:00 2001
From: oliver-statsig <oliver@statsig.com>
Date: Thu, 23 Jan 2025 16:29:23 -0800
Subject: [PATCH] Add description for API versioning (#2512)

---
 docs/console-api/autogenerated.mdx |  3 --
 docs/console-api/introduction.mdx  |  6 +++
 src/components/Rapidoc.js          | 61 ++++++++++++++++++++++++++++--
 3 files changed, 63 insertions(+), 7 deletions(-)

diff --git a/docs/console-api/autogenerated.mdx b/docs/console-api/autogenerated.mdx
index 3eb405194..14715e377 100644
--- a/docs/console-api/autogenerated.mdx
+++ b/docs/console-api/autogenerated.mdx
@@ -8,9 +8,6 @@ import Rapidoc from "../../src/components/Rapidoc"
 
 The endpoints below are the latest and auto-generated. While we strive to provide comprehensive descriptions and examples for each endpoint during this migration, if you notice any missing information or have feedback, please reach out to us on Slack.
 <br />
-<a href="https://api.statsig.com/openapi" download="https://api.statsig.com/openapi" class="download-button"><button>Download OpenAPI Specification</button></a>
-<br />
-<br />
 <Rapidoc id="all-endpoints-generated" entity='all-endpoints-generated'/>
 <div style={{
     paddingTop: 20,
diff --git a/docs/console-api/introduction.mdx b/docs/console-api/introduction.mdx
index 221fb066d..0522876f9 100644
--- a/docs/console-api/introduction.mdx
+++ b/docs/console-api/introduction.mdx
@@ -14,3 +14,9 @@ All requests must include the **STATSIG-API-KEY** field in the header. The value
 ## Rate Limiting
 
 Mutation requests (POST/PATCH/PUT/DELETE) to the Console API are limited to ~ 100 requests / 10 seconds and ~ 900 requests / 15 minutes.
+
+## API Version
+
+The Console API is versioned. Each version is guaranteed to not break existing usage; each new version introduces breaking changes. There is currently only one version: `20240601`.
+
+Pass the version in the **STATSIG-API-VERSION** field in the header. For now, this is optional; in the future, this will be required.
diff --git a/src/components/Rapidoc.js b/src/components/Rapidoc.js
index 4aff38e0a..e669699c0 100644
--- a/src/components/Rapidoc.js
+++ b/src/components/Rapidoc.js
@@ -1,5 +1,6 @@
+import { useEffect, useState } from "react";
+
 import Alert from "@mui/material/Alert";
-import { useEffect } from "react";
 
 // Map entities to their corresponding OpenAPI tags
 const entityToTagMap = {
@@ -23,15 +24,43 @@ const entityToTagMap = {
   keys: "Keys",
 };
 
+export const apiVersions = [
+  '20240601',
+];
+
+export function getSpecUrlForApiVersion(version) {
+  return `https://api.statsig.com/openapi/${version}.json`;
+}
+
+const SELECTED_API_VERSION_STORAGE_KEY = 'statsig_api_version';
+
 export default function Rapidoc(props) {
   const { id, entity } = props;
   const isDarkTheme = false;
+  const [apiVersion, setApiVersion] = useState(null);
+  const specUrl = apiVersion ? getSpecUrlForApiVersion(apiVersion) : null;
+
+  const setApiVersionToStorage = (version) => {
+    localStorage.setItem(SELECTED_API_VERSION_STORAGE_KEY, version);
+    setApiVersion(version);
+  }
+
+  useEffect(() => {
+    if (!apiVersion) {
+      // Can't have this in the useState init because it prevents this from being server renderable.
+      setApiVersion(localStorage.getItem(SELECTED_API_VERSION_STORAGE_KEY) ?? apiVersions[0]);
+    }
+  }, [apiVersion]);
 
   useEffect(() => {
+    if (!specUrl) {
+      return;
+    }
+
     const rapidoc = document.getElementById(id);
 
     if (entity === "all-endpoints-generated") {
-      rapidoc.loadSpec("https://api.statsig.com/openapi");
+      rapidoc.loadSpec(specUrl);
       return;
     }
 
@@ -39,7 +68,7 @@ export default function Rapidoc(props) {
     const tag = entityToTagMap[entity];
 
     // Fetch and filter the spec by tag
-    fetch("https://api.statsig.com/openapi")
+    fetch(specUrl)
       .then((response) => response.json())
       .then((data) => {
         if (tag) {
@@ -54,7 +83,7 @@ export default function Rapidoc(props) {
           rapidoc.loadSpec(data);
         }
       });
-  }, [entity]);
+  }, [specUrl, entity]);
 
   return (
     <rapi-doc
@@ -74,6 +103,9 @@ export default function Rapidoc(props) {
       server-url="https://statsigapi.net/console/v1"
       show-header={false}
       allow-authentication={true}
+      api-key-name="STATSIG-API-VERSION"
+      api-key-location="header"
+      api-key-value={apiVersion}
       regular-font={[
         "-apple-system",
         "BlinkMacSystemFont",
@@ -89,6 +121,17 @@ export default function Rapidoc(props) {
           {getDescription(entity)}
         </div>
 
+        <p>
+          API Version:{' '}
+          <select value={apiVersion} onChange={(e) => setApiVersionToStorage(e.target.value)}>
+            {apiVersions.map((version, idx) => (
+              <option value={version}>{version}{idx === 0 ? ' (latest)' : ''}</option>
+            ))}
+          </select>
+          {' '}
+          <a href={specUrl} download={specUrl} class="download-button"><button>Download OpenAPI Specification</button></a>
+        </p>
+
         <h2>Authorization</h2>
         <p>
           All requests must include the <code>STATSIG-API-KEY</code> field in the
@@ -98,6 +141,16 @@ export default function Rapidoc(props) {
           To use the 'try it' section on this page, enter your Console API into
           the box below.
         </p>
+        <h2>API Version</h2>
+        <p>
+          The Console API is versioned. Each version is guaranteed to not break
+          existing usage; each new version introduces breaking changes. There is
+          currently only one version: <code>20240601</code>.
+          <br />
+          Pass the version in the <code>STATSIG-API-VERSION</code> field in the
+          header. For now, this is optional; in the future, this will be
+          required.
+        </p>
         <hr />
       </div>
       <Alert severity="warning" slot="auth">