Overview

Overview

Prismatic provides a GraphQL-based API for you to build, deploy, and support your integrations programmatically. While we recommend that new users use the web app or Prismatic CLI tool to manage Prismatic resources, developer users will likely want to use the API to script out integration management.

What is GraphQL?

GraphQL is a data query language for APIs - it's like a hybrid of the best parts of REST and SQL. GraphQL allows you to:

  • Request exactly what you need, and nothing more. You can request specific information about resources, and get back exactly what you request without extraneous information.
  • Query for multiple resources with a single request. In a traditional REST API, you might make dozens of requests to various endpoints to gather the information you need. With GraphQL, you can query for multiple resources, including nested related resources, and get back all the results you need through a single query.
  • Pull down anything that you can view in the web app or CLI tool. Both the web app and CLI tool use GraphQL queries to populate their UIs. Anything that you can do in the web app can be done through the API.
  • Reference an API specification to sculpt your queries. GraphQL APIs offer a schema, so you know what fields are available for what resources, and how the resources are interrelated.

Why Prismatic Chose GraphQL

Prismatic chose to use GraphQL because of its power and flexibility. You can query the API however you like, and define exactly what data you want with a single query.

GraphQL allows Prismatic backend developers and API consumers to work independently of one another. If you need a new field, simply add the field to your query - there's no waiting for backend developers to modify REST endpoints.

Querying Prismatic's API with the GraphiQL Explorer

Prismatic's GraphiQL explorer lets you test queries against the Prismatic API. If you are logged in to the web app, you can perform authenticated queries against Prismatic's GraphQL API using the GraphiQL explorer.

Prismatic's GraphQL Schema

The left-hand sidebar of this page contains information about Prismatic's GraphQL schema, its operations, and schema-defined types.

GraphQL operations - queries (pulling data) and mutations (creating, modifying or deleting data) - describe the various CRUD operations you can complete through the API. Schema-defined types - scalars, objects, enums, interfaces, unions, and input objects - describe data types that you will encounter as you query the API.

You can access this same information in the GraphiQL explorer, as well, by clicking the Docs link on the top right of the GraphiQL page.

Additionally, GraphQL is introspective, meaning you can query the API for details about itself.

For example, you can query __schema for a list of all types defined in the schema and get details about each type:

query {
__schema {
types {
name
kind
description
fields {
name
}
}
}
}

You can then get information about a specific type by querying __type:

query {
__type(name: "User") {
name
kind
description
fields {
name
}
}
}

How Do I Get an API Authorization Token?

You will probably want to query the Prismatic API with tools outside of the GraphiQL explorer. To do that, you'll need an API token. When you authenticate against Prismatic through the web app or Prismatic CLI tool, your web browser or CLI tool receives a JWT that can be used to query the API.

If you are using the Prismatic CLI tool, you can use the subcommand me:token.

prism me:token
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJodHRwczovL3ByaXNtYXRpYy5pby9lbWFpbCI6IndlLmxvdmVAand0LmNvbSIsImh0dHBzOi8vcHJpc21hdGljLmlvL2VtYWlsX3ZlcmlmaWVkIjpmYWxzZSwiaXNzIjoiaHR0cHM6Ly9wcmlzbWF0aWMtaW8uYXV0aDAuY29tLyIsInN1YiI6ImF1dGgwfGFiYzEyMyIsImF1ZCI6WyJodHRwczovL3ByaXNtYXRpYy5pby9hcGkiLCJodHRwczovL3ByaXNtYXRpYy1pby5hdXRoMC5jb20vdXNlcmluZm8iXSwiaWF0IjoxNTg3NDg4MjU4LCJleHAiOjE1ODc1NzQ2NTgsImF6cCI6ImFiYzEyMyIsInNjb3BlIjoib3BlbmlkIHByb2ZpbGUgZW1haWwifQ.m6T8TATtckZcZ8xvbhlrN4tgmhrUqUQ_MGNmCLV8g7s

Use that token as part of your HTTP authorization header to authenticate your queries against the API.

Querying Prismatic's API with Another GraphQL Client

GraphQL Clients like the Google Chrome plugin from Altair or the Apollo Client Developer Tools Plugin can be used to query the API.

Take note of the token that you generated, and pass in an HTTP Authorization header

{ "Authorization": "Bearer {{TOKEN}}" }

For API endpoint, enter https://app.prismatic.io/api.

Querying Prismatic's API Programmatically

Most modern programming languages implement GraphQL client libraries. You can also curl -X POST queries against the GraphQL API.

In the example below we query the API for all Prismatic components and their labels, descriptions, keys, and whether authorization is required.

Using curl you can pass in a GraphQL query and authorization header.

API_KEY=$(prism me:token)
API_ENDPOINT='https://app.prismatic.io/api/'
QUERY='{
"query":
"query { components { nodes { label description key authorizationRequired } } }"
}'
curl ${API_ENDPOINT} -X POST \
-H "Content-Type: application/json" \
-H "Authorization: bearer ${API_KEY}" \
--data "$(echo $QUERY)"
Last updated on