Using the Prisma GraphQL API

Overview

Prisma APIs are consumed via HTTP. This means you can use any HTTP tool/library you like to talk to a Prisma API.

Here is the structure of an HTTP POST request that carries a createUser mutation:

Header

• Authorization: Carries the service token (prefixed with Bearer) used to authenticate a request; only required if the service is deployed with a service secret.
• Content-Type: Specifies the format of the request's body (JSON), usually application/json.

Body (JSON)

• query: The GraphQL operation to be sent to the API; beware that despite the field being called query it's also used for mutations!
• variables: A JSON object containing the variables defined in the GraphQL operation submitted in query.

All examples on this page are based on a Prisma service with the following service configuration:

prisma.yml

datamodel: datamodel.prisma
secret: my-secret-42

datamodel.prisma

type User {
  id: ID! @unique
  name: String!
}

curl

curl is a command-line tools that (among other things) lets you send HTTP requests to URLs.

Here is how you send a createUser mutation to the Prisma API using curl:

curl '__YOUR_PRISMA_ENDPOINT__' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer __YOUR_SERVICE_TOKEN__' \
--data-binary '{"query":"mutation ($name: String!) { createUser(data: { name: $name }) { id } }","variables":{"name":"Sarah"}}'

To try out this example, replace the __YOUR_PRISMA_ENDPOINT__ and __YOUR_SERVICE_TOKEN__ placeholders with corresponding values from your Prisma service and paste the resulting snippet into your terminal.

This results in the following mutation getting resolved by the Prisma API:

mutation {
  createUser(data: { name: "Sarah" }) {
    id
  }
}

Try out this example:

1. Replace the __YOUR_PRISMA_ENDPOINT__ and __YOUR_SERVICE_TOKEN__ placeholders with corresponding values from your Prisma service
2. Paste the resulting snippet into your terminal and hit enter

fetch (Node.JS)

The fetch function lets you to send HTTP requests to URLs from JavaScript.

Here is how you send a createUser mutation to the Prisma API using fetch in a Node script:

const fetch = require('node-fetch')

const endpoint = '__YOUR_PRISMA_ENDPOINT__'

const query = `
mutation($name: String!) {
  createUser(data: {
    name: $name
  }) {
    id
  }
}
`

const variables = { name: 'Sarah' }

fetch(endpoint, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'Bearer __YOUR_SERVICE_TOKEN__',
  },
  body: JSON.stringify({ query: query, variables: variables }),
})
  .then(response => response.json())
  .then(data => console.log(JSON.stringify(data)))

This results in the following mutation getting resolved by the Prisma API:

mutation {
  createUser(data: { name: "Sarah" }) {
    id
  }
}

Try out this example:

1. Replace the __YOUR_PRISMA_ENDPOINT__ and __YOUR_SERVICE_TOKEN__ placeholders with corresponding values from your Prisma service
2. Store the resulting snippet in a JavaScript file called script.js
3. Install the node-fetch library by running yarn add node-fetch in the same directory where script.js is located
4. Execute the script using the following terminal command: node script.js

graphql-request

The graphql-request library is a lightweight wrapper on top of fetch which you can use to save writing boilerplate code. It is mostly used in scripts and smaller applications that need to talk to a GraphQL API.

Using request

const { request } = require('graphql-request')

const query = `
mutation($name: String!) {
  createUser(data: {
    name: $name
  }) {
    id
  }
}
`

const variables = { name: 'Sarah' }

request('__YOUR_PRISMA_ENDPOINT__', query, variables).then(data =>
  console.log(data),
)

Try out this example:

1. Replace the __YOUR_PRISMA_ENDPOINT__ and __YOUR_SERVICE_TOKEN__ placeholders with corresponding values from your Prisma service
2. Store the resulting snippet in a JavaScript file called script.js
3. Install the graphql-request library by running yarn add graphql-request in the same directory where script.js is located
4. Execute the script using the following terminal command: node script.js

Using GraphQLClient

const { GraphQLClient } = require('graphql-request')

const client = new GraphQLClient('__YOUR_PRISMA_ENDPOINT__', {
  headers: {
    Authorization: 'Bearer __YOUR_SERVICE_TOKEN__',
  },
})

const query = `
mutation($name: String!) {
  createUser(data: {
    name: $name
  }) {
    id
  }
}
`

const variables = { name: 'Sarah' }

client.request(query, variables).then(data => console.log(data))

Try out this example:

1. Replace the __YOUR_PRISMA_ENDPOINT__ and __YOUR_SERVICE_TOKEN__ placeholders with corresponding values from your Prisma service
2. Store the resulting snippet in a JavaScript file called script.js
3. Install the graphql-request library by running yarn add graphql-request in the same directory where script.js is located
4. Execute the script using the following terminal command: node script.js

GraphQL Playground

A GraphQL Playground is a GraphQL IDE that lets you send queries, mutations and subscriptions to GraphQL APIs.

You can open a Playground for your Prisma API by navigating your terminal into the same directory where your service's prisma.yml is located and run the following command:

prisma playground

If your prisma.yml contains a secret, the opening Playground will already be configured with a service token. You can verify this in the HTTP HEADERS pane in the bottom-left corner:

This means you can start sending requests to the Prisma API right away. Queries, mutations and subscriptions are written in the left pane of the Playground. You then hit the Play-button to actually send the request. The results will appear in the right pane of the Playground:

Apollo Client

Apollo Client is a sophisticated GraphQL client library commonly used in larger frontend applications. While all previous examples used a generic utility to send queries and mutations alike, Apollo Client exposes dedicated methods for sending queries and mutations: query & mutate

query

const { ApolloClient } = require('apollo-boost')
const gql = require('graphql-tag')

const endpoint = 'https://eu1.prisma.sh/nikolas-burk/demodofin/dev'

const client = new ApolloClient({
  uri: endpoint,
})

const query = gql`
  query {
    users {
      id
      name
    }
  }
`

client
  .query({
    query: query,
  })
  .then(data => console.log(data))

mutate

const { ApolloClient } = require('apollo-boost')
const gql = require('graphql-tag')

const endpoint = 'https://eu1.prisma.sh/nikolas-burk/demodofin/dev'

const client = new ApolloClient({
  uri: endpoint,
})

const mutation = gql`
  mutation($name: String!) {
    createUser(data: { name: $name }) {
      id
    }
  }
`

const variables = { name: 'Sarah' }

client
  .mutate({
    mutation: mutation,
    variables: variables,
  })
  .then(data => console.log(data))