Quiltt Logo

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:

  1. Reduce the number of network requests required to get the data you need.
  2. Improve the type-safety of your application, letting GraphQL's strongly-typed schema do the heavy lifting.
  3. 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.

GraphQL API Reference

Profile →