Generating and Using queries

Overview

Now that we have setup everything it is time to get to the fun part, build something and demonstrate how easy these tools make the integration process of the Sanctuary Health API.

Setup our generation folders

From the previous section Installing GraphQL Code Generator we created our new command that we can run with npm run gen. If you run this command you will find it fails because there is nothing in our ./src/gql/ folder. Its always good to stay organized so lets start out by creating our ./src/gql/ folder and sub folders to place fragments and queries. This should look like this:

src
└───gql
    ├───fragments
    └───queries

GQL Tag

Now that we have our folders we can almost put some files in them. We will be using graphql-tag so that we can define GraphQL things easily. Fortunately this is re-exported from @apollo/client so we don't have to do anything.

note

If you are not using @apollo/client you can install this separately or use a similar tool

Our first query

Now we truly are ready to get suck in. Lets start by using the full passthrough query displayed in Queries with Arguments, but instead of calling the operation exampleOperation lets call it getPostsOperation. Also, instead of putting id and title directly in the query, lets make a Post fragment with these attributes as discussed in the Fragments section. This should look like the following:

./src/gql/fragments/postFragment.ts

import { gql } from "@apollo/client"

export const GRAPHQL = gql`
fragment postFragment on Post {
  id
  title
}
`

./src/gql/queries/getPostsOperation.ts

import { gql } from "@apollo/client"

export const GRAPHQL = gql`
query getPostsOperation($sequelizeQuery: SequelizeQuery!) {
  getPosts(sequelizeQuery: $sequelizeQuery) {
    ...postFragment
  }
}
`

Now for the moment of magic, after saving these files just run:

npm run gen

If everything went well we should now see our generated file at ./src/gql.tsx containing all the Typescript typings and React hooks useGetPostsOperationQuery and useGetPostsOperationLazyQuery. Use the normal query if you want to automatically pull the data on component load, or you can use the lazy query to fetch the data when you call a function. The queries can be called with the sequelizeQuery variable as configured in the operation, and will return data, loading and error values so you can customize your UI.

Use results

Now everything is sorted, lets get started by running our project in development mode, this should also open a browser tab showing your project. To do this just run:

npm start

You should now be able to see your project in your browser showing a grey background with a spinning React logo and instructions to edit your App.tsx. As instructed lets edit our App.tsx file by importing and using our freshly generated useGetPostsOperationQuery hook. This should look like this:

import { useGetPostsOperationQuery } from './gql';

And then lets call our hook at the start of our App component. This should look like this:

const {data, loading, error} = useGetPostsOperationQuery({variables: {sequelizeQuery: {}}})

Finally lets change the instruction to change App.tsx to print the JSON data returned by the Sanctuary Health API. This should look like this:

<p>
  {JSON.stringify(data)}
</p>

Our App.tsx file should now look like this:

./src/app.tsx

import React from 'react';
import logo from './logo.svg';
import './App.css';
import { useGetPostsOperationQuery } from './gql';

function App() {
  const {data, loading, error} = useGetPostsOperationQuery({variables: {sequelizeQuery: {}}})

  return (
    <div className="App">
      <header className="App-header">
        <img src={logo} className="App-logo" alt="logo" />
        <p>
          {JSON.stringify(data)}
        </p>
        <a
          className="App-link"
          href="https://reactjs.org"
          target="_blank"
          rel="noopener noreferrer"
        >
          Learn React
        </a>
      </header>
    </div>
  );
}

export default App;

If you now save your App.tsx file and then return to your browser your project will reload and then, after a brief period while the data is being fetched, the returned JSON data should display in the page.

Wrapping up

Obviously showing JSON data as a string is not pretty and nobody should really display the data in this way but this is where we hand over to you and your team. You should now have all the tools to pull data from the Sanctuary Health API and build a beautiful experience for your users, along with a project setup that enables automation to maximize both developer experience and delivery speed.

If you haven't already visited the GitHub repository for this worked tutorial you can find it here.

We would also love to hear your feed back on this example and are happy to help if anything was unclear. Please reach out via email to jamie@sanctuaryhealth.io.