Add description for API versioning

statsig-io · Jan 22, 2025 · 8a73319 · 8a73319
1 parent 8afb1e8
commit 8a73319
Show file tree

Hide file tree

Showing 3 changed files with 52 additions and 7 deletions.
diff --git 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
@@ -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
@@ -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,23 +24,40 @@ 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(localStorage.getItem(SELECTED_API_VERSION_STORAGE_KEY) || apiVersions[0]);
+  const specUrl = getSpecUrlForApiVersion(apiVersion);
+
+  const setApiVersionToStorage = (version) => {
+    localStorage.setItem(SELECTED_API_VERSION_STORAGE_KEY, version);
+    setApiVersion(version);
+  }
 
   useEffect(() => {
     const rapidoc = document.getElementById(id);
 
     if (entity === "all-endpoints-generated") {
-      rapidoc.loadSpec("https://api.statsig.com/openapi");
+      rapidoc.loadSpec(specUrl);
       return;
     }
 
     // Get the corresponding OpenAPI tag for the entity
     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 +72,7 @@ export default function Rapidoc(props) {
           rapidoc.loadSpec(data);
         }
       });
-  }, [entity]);
+  }, [specUrl, entity]);
 
   return (
     <rapi-doc
@@ -74,6 +92,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 +110,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 +130,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">