Skip to main content

Embedded API Requests

The embedded SDK allows you to embedded marketplace or the integration designer into your app. But, you may want to query for and display other data from the Prismatic API. By querying the Prismatic API, you can map data from the API into custom UI elements in your app, and you can completely customize your customers' experience as they manage and deploy integrations.

This article outlines how to fetch data from the Prismatic API using the embedded SDK. For information on how to install the embedded SDK and authenticate customer users, see Installing Embedded SDK

The Prismatic GraphQL API#

Prismatic's API is GraphQL-based. Full documentation on the API is available in the API docs, including several example queries and mutations. You can try out the Prismatic API using our GraphiQL explorer tool.

Embedded user scope and API permissions#

When you authenticate a customer user in the embedded SDK, that user is attached to one of your customers in Prismatic. The embedded customer user has permission to affect only the resources available to that customer (i.e. they cannot see other customers' integrations, instances, custom components, users, etc). They can, for example, use this query to fetch the instances that are deployed to their customer:

{  authenticatedUser {    customer {      instances {        nodes {          id          name        }      }    }  }}

Example embedded API requests#

Here are a few examples of what you can do through embedded API requests. All examples use prismatic.graphqlRequest, which takes two parameters:

  • query is a string that represents the query or mutation to send to the Prismatic API.
  • variables is a key-value object of variables to send with the query or mutation.

Listing deployed instances#

In this example, we fetch a list of instances from API and map them to <ul> elements. This example is simple, but illustrates how you can pull any data you want from the API and display it using whatever UI elements you choose.

Fetch and display data from the API
import { Button, Typography } from "@mui/material";import prismatic from "@prismatic-io/embedded";import { useState } from "react";
/** * Get a list of instances deployed to the current user's customer */const loadInstances = async (setInstances: Function) => {  const query = `{    authenticatedUser {      customer {        instances {          nodes {            id            name            flowConfigs {              nodes {                id                flow {                  name                }                apiKeys                webhookUrl              }            }          }        }      }    }  }`;  const result = await prismatic.graphqlRequest({ query });  setInstances(result.data.authenticatedUser.customer.instances.nodes);};
interface FlowConfig {  id: string;  flow: { name: string };  webhookUrl: string;}
interface Instance {  id: string;  name: string;  flowConfigs: {    nodes: FlowConfig[];  };}
function ListInstances() {  const [instances, setInstances] = useState<Instance[]>([]);
  return (    <>      <Typography variant="body1">        In this example, all instances that are currently deployed to the        current user's customer are listed, along with each instance's webhook        URLs.      </Typography>      <Button onClick={() => loadInstances(setInstances)} variant={"contained"}>        Load Instances...      </Button>      <ul>        {instances.map((instance) => (          <li key={instance.id}>            {instance.name} (<em>{instance.id}</em>)            <ul>              {instance.flowConfigs.nodes.map((flowConfig) => (                <li key={flowConfig.id}>                  {flowConfig.flow.name} -{" "}                  <a href={flowConfig.webhookUrl}>{flowConfig.webhookUrl}</a>                </li>              ))}            </ul>          </li>        ))}      </ul>    </>  );}
export default ListInstances;

Deploying an instance#

If your instance has minimal configuration (say, only a single OAuth flow to complete), you may want to skip the instance config wizard altogether. In this example, a single button is presented, "Deploy Dropbox". When that button is clicked, the current user's customer ID is fetched, along with the ID of the Dropbox integration. An instance of Dropbox is deployed, and a new window is opened where a user can complete the OAuth flow for the instance.

Deploy an instance without the config wizard
import { Button, Typography } from "@mui/material";import prismatic from "@prismatic-io/embedded";import { useState } from "react";
/** * Get the ID of the version of the Dropbox integration * that is available in the integration marketplace */const getDropboxVersionId = async () => {  const query = `query getMarketplaceIntegrations($name: String) {    marketplaceIntegrations(      name: $name      sortBy: [{field: CATEGORY, direction: ASC}, {field: NAME, direction: ASC}]    ) {      nodes {        id        name        versionSequence(first: 1, versionIsAvailable: true) {          nodes {            id            versionNumber          }        }      }    }  }`;  const variables = { name: "Dropbox" };
  const result = await prismatic.graphqlRequest({ query, variables });  return result.data.marketplaceIntegrations.nodes[0].versionSequence.nodes[0]    .id;};
/** * Get the current user's customer ID */const getCustomerId = async () => {  const query = `{    authenticatedUser {      customer {        id      }    }  }`;  const result = await prismatic.graphqlRequest({ query });  return result.data.authenticatedUser.customer.id;};
interface CreateInstanceProps {  dropboxVersionId: string;  customerId: string;  instanceName: string;}
/** * Create a new instance of the Dropbox integration, returning the * OAuth authorize URL where the user should be sent */const createInstance = async ({  dropboxVersionId,  customerId,  instanceName,}: CreateInstanceProps) => {  const query = `mutation createDropboxInstance($customerId: ID!, $integrationId: ID!, $instanceName: String!) {    createInstance(input: {customer: $customerId, integration: $integrationId, name: $instanceName}){      instance {        id        name        configVariables {          nodes {            authorizeUrl          }        }        flowConfigs {          nodes {            id            flow {              name            }            webhookUrl          }        }      }    }  }`;  const variables = {    customerId,    integrationId: dropboxVersionId,    instanceName,  };  const result = await prismatic.graphqlRequest({ query, variables });  return result;};
interface DeployInstanceProps {  instanceId: string;}
/** * Deploy the instance after configuration */const deployInstance = async ({ instanceId }: DeployInstanceProps) => {  const query = `mutation deployDropbox($instanceId: ID!){    deployInstance(input:{id:$instanceId}) {      instance {        lastDeployedAt      }    }  }`;  const variables = { instanceId };  await prismatic.graphqlRequest({ query, variables });};
interface Instance {  data?: {    createInstance: {      instance: { id: string };    };  };}
function DeployDropbox() {  const [instance, setInstance] = useState<Instance>({});  return (    <>      <Typography variant="body1">        In this example, an instance of an integration named Dropbox is created,        the user is redirected to an OAuth screen, and the instance is then        deployed. <br />        Note: this assumes that you have an integration in your marketplace called        "Dropbox", and that the integration has only one config variable - the Dropbox        connection.      </Typography>      <Button        onClick={async () => {          const customerId = await getCustomerId();          const dropboxVersionId = await getDropboxVersionId();          const dropboxInstance = await createInstance({            dropboxVersionId,            customerId,            instanceName: `Dropbox ${Math.floor(Number(new Date()))}`,          });          const oauthEndpoint =            dropboxInstance.data.createInstance.instance.configVariables              .nodes[0].authorizeUrl;          window.open(oauthEndpoint, "", "width=800, height=800");          setInstance(dropboxInstance);        }}        variant={"contained"}      >        Create Instance      </Button>      <Button        variant={"outlined"}        onClick={async () => {          const instanceId = instance.data?.createInstance.instance.id;          if (instanceId) {            await deployInstance({ instanceId });          }        }}      >        Deploy Instance      </Button>      <pre>{JSON.stringify(instance, null, 2)}</pre>    </>  );}
export default DeployDropbox;