Embedded API Requests
The embedded SDK allows you to embed the marketplace and 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.
For an example of querying the Prismatic API to generate a custom marketplace UI, see GitHub.
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:
queryis a string that represents the query or mutation to send to the Prismatic API.variablesis 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.
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.
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;