GraphQL Best Practices

We recommend the following best practices to ensure you're getting the best possible, most performant use out of Thinkific's GraphQL API.

In this article:

• Name Your Operations
• Only Request the Data You Need
• Slice and Paginate When Requesting Connections
• Test Queries to Optimize Them
• Use Fragments to DRY Up Your Code

Name Your Operations

Queries and mutations made with Thinkific's GraphQL API require a name. We suggest using PascalCase as a best practice, and operations that lack a name will return an error. Naming your operations provides a number of benefits:

• Your operation's purpose is immediately apparent
• You can include more than one operation in a query document (multiple anonymous operations cannot appear together)
• You improve the ability to debug your code (and our ability to troubleshoot issues on your behalf)

# Best Practice: Named Operations
query SiteQuery {
  site {
    name
  }
}

# Poor Practice
query {
  site {
    name
  }
}

Only Request the Data You Need

GraphQL allows you to build highly granular requests where you can target the exact data your app needs to function. Don't reuse a larger query when a more precise query would suffice. Specific queries improve the response time of your request and make your app more performant.

Public apps that request superfluous metadata will be rejected during the app listing review process.

Slice and Paginate When Requesting Connections

When making requests for connections, always include the pageInfo object with `hasNextPage` in your query. `hasNextPage` will tell you if there is more data outside of your returned results. This is especially helpful if the connection has more than 25 nodes (we return a maximum of 25 nodes at a time).

A `first` or `last` argument is required on all requests, so select a value between 1 and 25 to fetch exactly what you need. Over-fetching can have a negative impact on your app's performance.

# Best Practice: Slicing and Pagination
query CoursesPaginationQuery {
  site {
    courses (first:25) {
      edges {
        node {
          id
          name
        }
      }
      pageInfo {
        endCursor
        hasNextPage
      }
    }
  }
}

Test Queries to Optimize Them

Use Thinkific's GraphQL Explorer to test your queries to verify their query cost. This will ensure that you're not exceeding our query limits and gives you an opportunity to refine your query to get the most out of Thinkific's GraphQL API. 

Use Fragments to DRY Up Your Code

A Fragment is a group of fields that can be shared across multiple operations. If your app has consistent patterns where certain fields are required, use a Fragment. 

As a best practice, use fragments only when a group of fields are logically related to one another. Piecemeal fragments can be semantically difficult to parse after the fact. 

# Best Practice: Fragments
query UserQuery {
  site {
    users (first:50) {
      edges {
        node {
          ...UserInfo
        }
      }
     pageInfo {
        hasNextPage
        endCursor
      }  
    }
  }
}  

query AssignmentSubmissionsQuery {
  site {
    assignmentSubmissions (first:20) {
      edges {
        node {
         user {
            ...UserInfo
          }  
        }
      }
      pageInfo {
        hasNextPage
        endCursor
      }
    }
  }
}

fragment UserInfo on User {
  firstName
  lastName
  email
}