Interacting with a user's data with 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 and reviewing our GraphQL Overview.
Link to this section#Endpoint
All GraphQL operations are served through a single endpoint:
POSThttps://api.quiltt.io/v1/graphql
Link to this section#Headers
Requests must be authenticated with a Profile's Session token, and specify an application/json
content type:
Authorization: Bearer <SESSION_TOKEN>
Content-Type: application/json
For server-to-server use-cases, Basic authentication is also supported. See the Authentication guide for more details.
Link to this section#Getting Data with Queries
Queries allow you to fetch data pertaining to the user, such as their profile, accounts and transactions.
A powerful feature of queries is that they natively support requesting complex, nested data structures. This allows you to:
- Reduce the number of network requests required to get the data you need.
- Improve the type-safety of your application, letting GraphQL's strongly-typed schema do the heavy lifting.
- Pass predictable, structured query responses to components trees in a frameworks like ReactJS.
Link to this section#profile Example
In this example, we will define a profile
query to get the user's basic profile details:
query GetProfile {
profile {
id
email
name
phone
address {
city
state
}
}
}
Link to this section#Request
curl --request POST \
--url 'https://api.quiltt.io/v1/graphql' \
--header 'Authorization: Bearer <SESSION_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
"query": "query GetProfile {
profile {
id
email
name
phone
address {
city
state
}
}
}",
"variables": null,
"operationName": "Profile"
}'
In GraphQL, successful queries always return a data
object that mirrors the structure of your request.
Link to this section#Response
{
"data": {
"profile": {
"id": "p_11oaRngjEOLf1YcBdZqKp0E",
"email": "[email protected]",
"name": null,
"phone": null,
"address": {
"city": "Dallas",
"state": "TX"
}
}
}
}
Link to this section#Changing Data with Mutations
Mutations allow you to add, update or remove data pertaining to the authenticated user, such as their profile, connections or accounts.
GraphQL natively supports performing multiple mutations in one request. Keep in mind that if you define multiple mutations in a single request, they will be executed sequentially in the order they're defined. This ensures that data from an earlier mutation is available to subsequent mutations.
Link to this section#profileUpdate Example
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
}
}
}
Link to this section#Request
curl --request POST \
--url 'https://api.quiltt.io/v1/graphql' \
--header 'Authorization: Bearer <SESSION_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
"query": "mutation UpdateName($name: String) {
profileUpdate(input: {name: $name}) {
success record {
id
name
}
errors {
message
path
}
}
}",
"variables":{ "name":"Quiltty" },
"operationName":"UpdateName"
}'
Link to this section#Response
{
"data": {
"profileUpdate": {
"success": true,
"record": {
"id": "p_11oaRngjEOLf1YcBdZqKp0E",
"name": "Quiltty"
},
"errors": null
}
}
}
Each mutation response will return a success
status (true
|false
), along with either the record
object or an errors
array.
Link to this section#Libraries
The examples above were made as simple cURL 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 implemented using Apollo Client's React hooks.
import * as React from 'react'
import { gql, useQuery } from '@apollo/client'
// Set up your query string to fetch the user's profile.
// Note that fetching the `id` allows Apollo's caching layer to
// keep the latest data in sync across various components.
const GET_PROFILE = gql`
query {
profile {
id
email
name
phone
}
}
`
export const Profile: React.FC = () => {
// Use the Apollo `useQuery` hook
const { loading, data } = useQuery(GET_PROFILE)
// Display a message while the query is in progress
if (loading) return <p>Loading...</p>
// Render the user's name from the response
return <p>Welcome back {data.profile.name}!</p>
}
Link to this section#API Reference
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.