[Schema] - Validate integration field API response shape before Configure step

cypress/e2e/schema/integration.spec.js

@@ -148,6 +148,59 @@ describe("Integration Field", () => {
           .should("have.length", 1);
       });
     });
+
+    context("Invalid Response Shape", () => {
+      const invalidShapes = [
+        { name: "null", body: null },
+        { name: "empty array", body: [] },
+        {
+          name: "single object with no nested array",
+          body: { name: "Solo", id: 1 },
+        },
+        { name: "array of primitives", body: [1, 2, 3, 4, 5] },
+        { name: "array of objects with no selectable keys", body: [{}] },
+      ];
+
+      invalidShapes.forEach(({ name, body }) => {
+        it(`blocks advancing and shows an error for: ${name}`, () => {
+          cy.intercept("**/get-url?url=*", { statusCode: 200, body }).as(
+            "getUrl"
+          );
+
+          cy.visit(`/schema/${Cypress.env("modelZUID")}/fields`);
+          cy.getBySelector("AddFieldBtn").click();
+          cy.getBySelector("FieldItem_integration").click();
+          cy.getBySelector("integrationConfigureButton").click();
+          cy.getBySelector("integrationFormDialog").should("exist");
+          cy.getBySelector("integrationEndpointInput")
+            .find("input")
+            .clear()
+            .type(ENDPOINTS.generic);
+
+          cy.getBySelector("integrationConnectButton").click();
+          cy.wait("@getUrl");
+
+          cy.getBySelector("integrationConnectionStatusContainer").should(
+            "exist"
+          );
+          cy.getBySelector("integrationConnectionStatusLabel").should(
+            "contain",
+            "Unsupported Response Format"
+          );
+          cy.getBySelector("integrationConnectionStatusSubtitle")
+            .invoke("text")
+            .should("not.be.empty");
+
+          // The action button must keep the user on the Connect step, not
+          // advance to Display Type where the Configure dead-end would occur.
+          cy.getBySelector("integrationConnectionStatusButton").click();
+          cy.getBySelector("integrationEndpointInput").should("exist");
+          cy.getBySelector("integrationSelectDisplayOptionsDialog").should(
+            "not.exist"
+          );
+        });
+      });
+    });
   });
 
   describe("Item Selection", () => {

src/shell/components/FieldTypeIntegration/Configure/ConfigureDisplayOptions.tsx

@@ -30,52 +30,7 @@ import { get } from "lodash";
 import { IntegrationKeyPaths, IntegrationTypes } from "../../../services/types";
 import KeyPathSelector from "./KeyPathSelector";
 import DisplayCard from "../Shared/DisplayCard";
-
-const isObj = (v: unknown): v is object => typeof v === "object" && v !== null;
-
-const getObjectKeyPaths = (obj: object): string[] => {
-  const acc: string[] = [];
-  const walk = (node: object, prefix: string): void => {
-    const arr = Array.isArray(node);
-    for (const key in node) {
-      if (!Object.prototype.hasOwnProperty.call(node, key)) continue;
-      const value = (node as Record<string, unknown>)[key];
-      const path = prefix
-        ? arr
-          ? `${prefix}[${key}]`
-          : `${prefix}.${key}`
-        : key;
-      if (isObj(value)) walk(value, path);
-      else acc.push(path);
-    }
-  };
-  walk(obj, "");
-  return acc;
-};
-
-const getAllArrayKeyPaths = (obj: object): string[] => {
-  const acc: string[] = [];
-  const walk = (node: object, prefix: string): void => {
-    const arr = Array.isArray(node);
-    for (const key in node) {
-      if (!Object.prototype.hasOwnProperty.call(node, key)) continue;
-      const value = (node as Record<string, unknown>)[key];
-      const path = prefix
-        ? arr
-          ? `${prefix}[${key}]`
-          : `${prefix}.${key}`
-        : key;
-      if (Array.isArray(value)) {
-        if (value.some(isObj)) acc.push(path);
-        walk(value, path);
-      } else if (isObj(value)) {
-        walk(value, path);
-      }
-    }
-  };
-  walk(obj, "");
-  return acc;
-};
+import { getObjectKeyPaths, getAllArrayKeyPaths } from "./keyPathHelpers";
 
 const ConfigureDisplayOptions = ({
   type,

src/shell/components/FieldTypeIntegration/Configure/ConnectToApi.tsx

@@ -73,6 +73,18 @@ const CONNECTION_STATUSES: {
     variant: "contained",
     color: "primary",
   },
+  invalid: {
+    icon: (
+      <InfoRoundedIcon fontSize="large" color="error" sx={{ fontSize: 40 }} />
+    ),
+    title: "Unsupported Response Format",
+    subTitle:
+      "The API connected, but its response can't be used to configure this field.",
+    buttonLabel: "Try Again",
+    buttonIcon: <AutorenewRoundedIcon fontSize="small" sx={{ fontSize: 40 }} />,
+    variant: "contained",
+    color: "primary",
+  },
 };
 
 const ConnectToApi = ({
@@ -95,7 +107,7 @@ const ConnectToApi = ({
   closeForm?: () => void;
 }) => {
   const focusRef = useRef<string>("url");
-  const { data, status, fetchApiData } = useIntegrationField();
+  const { data, status, invalidReason, fetchApiData } = useIntegrationField();
 
   const [isValidUrl, setIsValidUrl] = useState(true);
   const [reqAborted, setReqAborted] = useState<boolean>(false);
@@ -395,12 +407,15 @@ const ConnectToApi = ({
               {CONNECTION_STATUSES[status].title}
             </Typography>
             <Typography
+              data-cy="integrationConnectionStatusSubtitle"
               variant="body2"
               color="text.primary"
               fontWeight={400}
               textAlign="center"
             >
-              {CONNECTION_STATUSES[status].subTitle}
+              {status === "invalid"
+                ? invalidReason
+                : CONNECTION_STATUSES[status].subTitle}
             </Typography>
           </Box>
           <Button

src/shell/components/FieldTypeIntegration/Configure/keyPathHelpers.ts

@@ -0,0 +1,46 @@
+export const isObj = (v: unknown): v is object =>
+  typeof v === "object" && v !== null;
+
+export const getObjectKeyPaths = (obj: object): string[] => {
+  const acc: string[] = [];
+  const walk = (node: object, prefix: string): void => {
+    const arr = Array.isArray(node);
+    for (const key in node) {
+      if (!Object.prototype.hasOwnProperty.call(node, key)) continue;
+      const value = (node as Record<string, unknown>)[key];
+      const path = prefix
+        ? arr
+          ? `${prefix}[${key}]`
+          : `${prefix}.${key}`
+        : key;
+      if (isObj(value)) walk(value, path);
+      else acc.push(path);
+    }
+  };
+  walk(obj, "");
+  return acc;
+};
+
+export const getAllArrayKeyPaths = (obj: object): string[] => {
+  const acc: string[] = [];
+  const walk = (node: object, prefix: string): void => {
+    const arr = Array.isArray(node);
+    for (const key in node) {
+      if (!Object.prototype.hasOwnProperty.call(node, key)) continue;
+      const value = (node as Record<string, unknown>)[key];
+      const path = prefix
+        ? arr
+          ? `${prefix}[${key}]`
+          : `${prefix}.${key}`
+        : key;
+      if (Array.isArray(value)) {
+        if (value.some(isObj)) acc.push(path);
+        walk(value, path);
+      } else if (isObj(value)) {
+        walk(value, path);
+      }
+    }
+  };
+  walk(obj, "");
+  return acc;
+};

src/shell/components/FieldTypeIntegration/useIntegrationField.ts

@@ -1,11 +1,71 @@
 import { useState, useEffect, useCallback, useRef } from "react";
 import { useGetExternalApiMutation } from "shell/services/cloudFunctions";
+import {
+  isObj,
+  getObjectKeyPaths,
+  getAllArrayKeyPaths,
+} from "./Configure/keyPathHelpers";
+
+// Mirrors the shape-walking that ConfigureDisplayOptions does when deriving
+// its key-selector options, so a response classified "ok" here is guaranteed
+// to actually produce selectable options there (and vice versa).
+export function classifyApiResponse(
+  apiData: unknown
+): { ok: true } | { ok: false; reason: string } {
+  if (apiData === null || apiData === undefined) {
+    return {
+      ok: false,
+      reason: "API returned no data. Expected a JSON array of objects.",
+    };
+  }
+
+  if (Array.isArray(apiData)) {
+    if (!apiData.length) {
+      return {
+        ok: false,
+        reason:
+          "API returned an empty array. Add at least one item to the response to configure display options.",
+      };
+    }
+    if (!isObj(apiData[0])) {
+      return {
+        ok: false,
+        reason: `API returned an array of ${typeof apiData[0]}s. Expected an array of objects.`,
+      };
+    }
+    if (!getObjectKeyPaths(apiData[0]).length) {
+      return {
+        ok: false,
+        reason:
+          "API returned an array of objects with no selectable keys. Make sure each object has at least one scalar property.",
+      };
+    }
+    return { ok: true };
+  }
+
+  if (isObj(apiData)) {
+    if (!getAllArrayKeyPaths(apiData).length) {
+      return {
+        ok: false,
+        reason:
+          "API returned a single object with no array of objects nested inside. Expected either an array root or an object containing an array of objects.",
+      };
+    }
+    return { ok: true };
+  }
+
+  return {
+    ok: false,
+    reason: `API returned a ${typeof apiData}. Expected a JSON array of objects.`,
+  };
+}
 
 const useIntegrationField = () => {
   const [apiData, setApiData] = useState<any>(null);
   const [status, setStatus] = useState<
-    "connecting" | "success" | "failed" | null
+    "connecting" | "success" | "failed" | "invalid" | null
   >(null);
+  const [invalidReason, setInvalidReason] = useState<string>("");
   const [getExternalApi, { data }] = useGetExternalApiMutation();
 
   const currentEndpointRef = useRef<string>("");
@@ -23,6 +83,7 @@ const useIntegrationField = () => {
       currentEndpointRef.current = endpoint;
       setStatus("connecting");
       setApiData(null);
+      setInvalidReason("");
 
       try {
         const response: any = await getExternalApi({
@@ -33,6 +94,13 @@ const useIntegrationField = () => {
 
         if (!response?.error) {
           const responseData = await response.data;
+          const classification = classifyApiResponse(responseData);
+          if (classification.ok === false) {
+            setApiData(null);
+            setInvalidReason(classification.reason);
+            setStatus("invalid");
+            return;
+          }
           setApiData(responseData);
           setStatus("success");
         } else {
@@ -56,12 +124,14 @@ const useIntegrationField = () => {
       currentEndpointRef.current = "";
       setApiData(null);
       setStatus(null);
+      setInvalidReason("");
     };
   }, []);
 
   return {
     data: apiData,
     status,
+    invalidReason,
     fetchApiData,
   };
 };