Skip to main content

GraphQL API Introduction

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 2500 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 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