Skip to main content

GraphQL

About GraphQL​

All data in Helium flows through GraphQL, an extremely modern and open-source data query and manipulation language for APIs. GraphQL APIs differs from REST API’s in various ways, but at the heart of it, GraphQL has greater flexibility and efficiency in terms of data access and management.

There are two ways to interact with GraphQL in Helium apps: the more general useQuery hook and other more specific hooks for specific data groups. An example of these more specific hooks is the useCatalogQuery hook which fetches specific data about catalog contents. Any hook provided by the Helium packages can replicated with useQuery–the provided hooks exist to make it easier to start and maintain Helium apps.

Authentication and Endpoint​

GraphQL queries and mutations are executed by sending POST HTTP requests to the endpoint https://{learning_instance}.com/helium

All GraphQL queries and mutations require an API access token. Include your token as a param for all requests like so https://{learning_instance}.com/helium?apiKey=**************

Rate Limits​

In order for a request to be processed, there are 3 limitations that must be met:

  • A single query must not exceed a calculated complexity of 1000 points.
  • Each instance is allotted 100,000 points per minute. This is not on a rolling basis; the points allowance resets 60 seconds from the first request.
  • The instance can not exceed 1000 requests per minute, regardless of complexity or points allowance.

Helium is meant to scale with your learning instance. If you have any concerns on limitations, please reach out to us.

Calculating Complexity​

Each requested property costs 1 point by default.

// Query example
query {
    CurrentUser {
        firstName
        lastName
    }
}

// 1 (firstName) + 1 (lastName) = a 2 point query

Certain queries types, such as CourseViews or Courses may have an additional cost as they require more resource-intensive queries.

// Query Example
query {
    CatalogContent {
        id
        title
        slug
    }
}

// 1(id) + 1(title) + 1(slug) + 3(performance cost) = a 6 point query

Additional Rate Limiting Information​

Information related to points can be found in the following headers:

  • X-RateLimit-Remaining: Number of allotted points remaining in the current duration
  • X-RateLimit-Reset: Timestamp at which point the allotted points will reset
  • Retry-After: Received only after exceeding a limit, denotes the number of seconds to wait before attempting the request again

Auth Tokens​

A user’s Auth Token is valid for as long as they have it configured for that particular role in the Role Settings in the Thought Industries Admin UI. More documentation on that can be found here. A users Auth Token is generated by calling the Login mutation.

Inside a Helium app, Auth Tokens are handled automatically with pageContext. When calling GraphQL from an outside client such as Postman, pass the Auth Token in the header of the request with the key as Auth Token and the value as what’s returned from the Login mutation.

If the Login mutation is called again (during the time period the current Auth Token is valid), a new token will be created (with the same duration til expiration as configured starting from that point).

GraphQL Explorer​

Helium also comes with GraphiQL, an extremly useful GraphQL explorer and playground. To use GraphiQL, start a local Helium web server, and go to http://localhost:3000/graphiql. GraphiQL is an extremely useful tool for writing, testing, and validating GraphQL queries before you use them in your actual code.

Postman Collection​

You can explore our GraphQL API though our Postman collection. You’ll have to define your URL and API Key variables.

Run in Postman

Use of template literals and string interpolation​

During the deployment phase, GraphQL operations are extracted from the project pre-compilation for hashing utilizing the @graphql-tools/graphql-tag-pluck library. The library relies on a gql tag being present before the opening template literal to identify GraphQL operations. This should be kept in mind when writing GraphQL operations in your code:

/// recommended
import React from 'react';
import { gql, useQuery } from '@apollo/client';

const EXAMPLE_QUERY = gql`
  query ExampleQuery($id: ID!) {
    ExampleOperation(id: $id) {
      name
    }
  }
`;

const Page = props => {
  const { data } = useQuery(EXAMPLE_QUERY);
  return <div>{data.name}</div>;
};

// not recommended
import React from 'react';
import { gql, useQuery } from '@apollo/client';

const EXAMPLE_QUERY = `
    query ExampleQuery($id: ID!) {
        ExampleOperation(id: $id) {
            name
        }
    }
`;

const Page = props => {
  const { data } = useQuery(
    gql`
      ${EXAMPLE_QUERY}
    `
  );
  return <div>{data.name}</div>;
};

Still have a question?​

Get your questions answered in our Developer Discord.

graphQL