How to Interact with a User's Data via GraphQL
Quiltt uses GraphQL as the primary API interface for an individual user’s data. If you are new to GraphQL, we recommend trying out the introductory materials at GraphQL.org.
AnchorAbout 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.
AnchorAuthenticating
Using the GraphQL endpoint requires a Session Token, sent in the Authorization
HTTP header of your request:
Authorization: Bearer {{SESSION_TOKEN}}
Once you’ve obtained the token, you can perform various queries and mutations related to the user.
AnchorSample Query: `profile`
In this example, we will define a query
to get the user’s basic profile details, and send it to our /graphql
endpoint.
query GetProfile { profile { email id name phone }}
AnchorRequest
AnchorResponse
HTTP/1.1 200 OK
{ "data": { "profile": { "email": "example@quiltt.io", "id": "3baa7624-2053-46b4-93f6-9132ce6ec65a", "name": null, "phone": null } }}
Note that the response data
object always mirrors the structure of the query
.
AnchorSample Mutation: `profileUpdate`
To update the user’s profile, we can send a mutation like this:
mutation UpdateName($name: String) { profileUpdate(input: { name: $name }) { success record { id name } errors { message path } }}
AnchorRequest
AnchorResponse
HTTP/1.1 200 OK
{ "data": { "profileUpdate": { "success": true, "record": { "id": "3baa7624-2053-46b4-93f6-9132ce6ec65a", "name": "Quiltty" }, "errors": null } }}
Each mutation response can return a success
status (true
|false
), along with a record
and errors
objects, based on the fields specified in your request.
AnchorLibraries
The examples requests above were made as 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 that seamlessly plug-in to your client-side or server-side framework of choice.
For example, here’s the 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 { email id name phone } }`
const Profile: React.VFC = () => { const { loading, data } = useQuery(GET_PROFILE);
if (loading) return <p>Loading...</p>
return <p>Welcome back {data.profile.name}!</p>}
Note: By fetching the profile id
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 our interactive GraphQL Explorer in the Quiltt Dashboard.