Embedded API Requests
The embedded SDK enables you to embed the marketplace and workflow builder into your application. But, you may want to query and display additional data from the Prismatic API. By leveraging the Prismatic API, you can map API data into custom UI components and fully customize your customers' integration management and deployment experience.
This article details how to fetch data from the Prismatic API using the embedded SDK. For information on installing the embedded SDK and authenticating customer users, see Installing Embedded SDK.
For an example of querying the Prismatic API to implement a custom marketplace UI, see GitHub.
The Prismatic GraphQL API
Prismatic's API is built on GraphQL. Comprehensive API documentation is available in the API docs, including example queries and mutations. You can test the Prismatic API using our GraphiQL explorer tool.
Embedded user scope and API permissions
When you authenticate a customer user through the embedded SDK, that user is associated with one of your customers in Prismatic. The embedded customer user has access permissions limited to resources available to that specific customer (i.e., they cannot access other customers' integrations, instances, custom components, users, etc.). For example, they can execute this query to retrieve instances deployed to their customer:
{
authenticatedUser {
customer {
instances {
nodes {
id
name
}
}
}
}
}
Example embedded API requests
The following examples demonstrate common use cases for embedded API requests.
All examples utilize prismatic.graphqlRequest, which accepts two parameters:
query: A string representing the GraphQL query or mutation to execute against the Prismatic API.variables: An object containing key-value pairs of variables to include with the query or mutation.
Listing deployed instances
This example retrieves a list of instances from the API and renders them as <ul> elements.
While simple, it demonstrates how to fetch arbitrary data from the API and render it using custom UI components.
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
For instances with minimal configuration requirements (e.g., only a single OAuth flow), you may want to bypass the instance configuration wizard. This example presents a "Deploy Dropbox" button that, when clicked, retrieves the current user's customer ID and the Dropbox integration ID. It then deploys a Dropbox instance and opens a new window for the user to complete the OAuth flow.
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;