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

cypress/e2e/schema/integration.spec.js

@@ -150,6 +150,63 @@ 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: [{}] },
+        {
+          name: "single object with nested array of empty objects",
+          body: { items: [{}] },
+        },
+      ];
+
+      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/ConnectToApi.tsx

@@ -77,6 +77,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 = ({
@@ -103,7 +115,7 @@ const ConnectToApi = ({
   keyPaths?: IntegrationKeyPaths | null;
 }) => {
   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);
@@ -409,12 +421,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
+                : CONNECTION_STATUSES[status].subTitle}
             </Typography>
             {keyPathsMismatch && (
               <Typography

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

@@ -1,7 +1,8 @@
 import { get } from "lodash";
 import { IntegrationKeyPaths } from "../../../services/types";
 
-const isObj = (v: unknown): v is object => typeof v === "object" && v !== null;
+export const isObj = (v: unknown): v is object =>
+  typeof v === "object" && v !== null;
 
 export const getObjectKeyPaths = (obj: object): string[] => {
   const acc: string[] = [];

src/shell/components/FieldTypeIntegration/useIntegrationField.ts

@@ -1,11 +1,84 @@
 import { useState, useEffect, useCallback, useRef } from "react";
+import { get } from "lodash";
 import { useGetExternalApiMutation } from "shell/services/cloudFunctions";
+import {
+  isObj,
+  getObjectKeyPaths,
+  getAllArrayKeyPaths,
+} from "./Configure/keyPathResolution";
+
+// 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)) {
+    const arrayPaths = getAllArrayKeyPaths(apiData);
+    if (!arrayPaths.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.",
+      };
+    }
+    const hasUsableArray = arrayPaths.some((path) => {
+      const item = get(apiData, path)?.[0];
+      return isObj(item) && getObjectKeyPaths(item).length > 0;
+    });
+    if (!hasUsableArray) {
+      return {
+        ok: false,
+        reason:
+          "API returned an object whose nested arrays contain no selectable keys. Make sure at least one nested array item has scalar properties.",
+      };
+    }
+    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 +96,7 @@ const useIntegrationField = () => {
       currentEndpointRef.current = endpoint;
       setStatus("connecting");
       setApiData(null);
+      setInvalidReason("");
 
       try {
         const response: any = await getExternalApi({
@@ -33,6 +107,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 +137,14 @@ const useIntegrationField = () => {
       currentEndpointRef.current = "";
       setApiData(null);
       setStatus(null);
+      setInvalidReason("");
     };
   }, []);
 
   return {
     data: apiData,
     status,
+    invalidReason,
     fetchApiData,
   };
 };