GraphQL How to use GraphQL

2 min read

Published

Updated


Quiltt uses GraphQL as the primary user data endpoint. If you are new to GraphQL, we recommend trying out the introductory materials at GraphQL.org.

About GraphQL

GraphQL is a modern and flexible API spec that allows the requesting client to design the response to suit their needs. Rather than having to page through many REST responses containing data that you don't need, you can craft a concise and specific request that is guaranteed to return only the details you do need.

Compounding this flexibility is the option to pack multiple queries and mutations into a single call to apply and retrieve changes all at once. Additionally, you can also batch requests using tools like Apollo Client, which will, for example, automatically roll up different requests from various components of your React.js app.

Authenticating

To use the GraphQL endpoint, you need to obtain a User Session Token for one of your users.

Sample Query

In this example, we will define a query to get the user's basic profile details, and send it to our /graphql endpoint.

query Profile {
  profile {
    email
    id
    name
    phone
  }
}
HTTP/1.1 200 OK

{
  "data": {
    "profile": {
      "email": "example@quiltt.io",
      "id": "00000000-0000-0000-0000-000000000000",
      "name": null,
      "phone": null
    }
  }
}
Note that the response data object always mirrors the structure of the query

Sample Mutation

Similarly, to update the user's profile, we might send a mutation like this:

mutation SetName($name: String) {
  profileUpdate(input: {name: $name}) {
    success
    record {
      id
      name
    }
    errors {
      message
      path
    }
  }
}
HTTP/1.1 200 OK

{
  "data": {
    "profileUpdate": {
      "success": true,
      "record": {
        "id": "00000000-0000-0000-0000-000000000000",
        "name": "Quiltty"
      },
      "errors": null
    }
  }
}

Each mutation response will return a success status, and either a record or errors objects, with the fields you specify in your request.

Libraries

As you saw above, these requests can be made like classic HTTP requests. However, there is a wealth of open-source clients and libraries provided by the GraphQL community, as well as extensions from Quiltt.

For example, here's our profile query example, using React Hooks with Apollo Client, as found in our react starter template:

import * as React from 'react'
import { gql, useQuery } from '@apollo/client'

const GET_PROFILE = gql`
  query {
    profile {
      id
      name
    }
  }
`

export const Profile: React.VFC = () => {
  const { loading, data } = useQuery(GET_PROFILE);

  if(loading) return <p>Loading...</p>

  return <p>Hello {data.profile.name}!</p>
}
Note how we ask for the profile id; by doing this, we enable Apollo's caching layer to update automatically and keep the latest data in sync across various components.

Since GraphQL is strongly typed and self-documenting, the best way to explore our schema is with QuilttGraphiQL, our interactive API Explorer.  Contact team@quiltt.io to request access.