Core Components Overview

This section covers the core concepts of GraphQL - schema, types, queries, mutations, and subscriptions - providing a clear foundation for working with APIs.

Schema

A GraphQL schema defines the structure of the API, outlining the data entities, their relationships, and the operations you can perform. These operations fall into three categories:

Queries  – similar to GET in REST, used to retrieve data.
Mutations  – like POST, PUT, PATCH, or DELETE, used to modify data.
Subscriptions  – for real-time updates.

Together, these operations define how you interact with the data. The schema acts as a contract between the client-side and server-side, ensuring consistency and clarity in how data is requested and delivered.

For more information on schema, visit GraphQL.com’s Schema section.

Types

Types describe the elements of a GraphQL schema, including basic data types like strings and numbers, as well as custom objects and structured inputs used in queries and mutations.

GraphQL supports:

Scalar Types – basic values like Int, Float, String, Boolean, and ID, plus custom scalars like Date, JSON, URL, etc.
Object Types – custom structured data with named fields used in queries and responses.
Enum Types – define a fixed set of allowed values for a field.
Input Types – structured data passed into queries or mutations.
Union & Interface Types – enable polymorphism by allowing fields to return varied object types through a shared structure

For more information on types, visit GraphQL.com’s Schema section.

Queries

A query is a GraphQL read operation used to retrieve data - similar to a GET request in REST. Unlike REST, which returns a fixed response shape, GraphQL lets you define exactly what the response should include. This precision allows you to combine related data in a single request, reducing the need for multiple calls to different endpoints and improving overall efficiency.

For more information on queries, visit GraphQL.com’s The Query section.

Mutations

A mutation is a GraphQL write operation used to modify server-side data. Mutations allow you to create, update, or delete records - similar to POST, PUT, PATCH, or DELETE in REST. Unlike REST, which often requires multiple endpoints for different actions, GraphQL mutations can handle all these operations through a single, structured request.

For more information on mutations, visit GraphQL.com’s Mutations section.

Fragments

GraphQL fragments allow you to reuse common field selections across multiple queries, mutations, or subscriptions.

They help keep your schema interactions consistent and maintainable, especially when working with complex types or repeating sets of fields.

By defining a fragment, you can avoid duplication and ensure that changes to shared fields only need to be updated in one place. This approach improves readability and reduces the risk of errors in large queries.

Fragments are declared with the fragment keyword and can be included in operations using the spread operator (...). They are ideal for scenarios where you need to standardise data retrieval across different parts of your application.

For more information on fragments, visit GraphQL.com's Fragments section.

Subscriptions

GraphQL subscriptions enable real-time communication between the client-side and server-side. They are ideal for use cases where live updates are essential - such as monitoring system status, receiving alerts, or tracking data changes as they occur.

Once a subscription is established, the server maintains a persistent connection via WebSockets or server-sent events) and pushes updates to the client whenever the subscribed data changes. This approach eliminates the need for polling, reducing overhead and latency, and ensures users always see the most current information.

For more information on subscriptions, visit GraphQL.org's Subscriptions section.

Authorization

After authenticating in GraphQL, you must include the API token you’ve generated in your request headers. This token determines what data you’re allowed to access.

To learn how to generate an N-able API token, visit Authentication.

For more information on authorization, visit GraphQL.org's Authorization section.

Pagination

Pagination is GraphQL’s solution for efficiently fetching large sets of data. This API follows the Relay Cursor Connection Specification, which enables precise control over how data is retrieved in chunks. Each response includes edges that wrap individual nodes and provide cursors for navigating forward or backward through the dataset.

Supported pagination limits:

Top-level items: Maximum page size is 100 items, with a default of 20 items.
Nested items: Maximum page size is 10 items, with a default of 5 items.

This approach helps optimise performance and reduce payload size, especially when working with complex or deeply nested queries.

Example query to fetch all organizations:

query GetAllOrganizations($first: Int, $after: String) {
  organizationSearch(first: $first, after: $after) {
    edges {
      cursor
      node {
        id
        name
      }
    }
    pageInfo {
      endCursor
      hasNextPage
    }
  }
}

Variables:

{
  "first": 20,
  "after": null
}

These variables control how data is fetched in pages for efficient navigation through large datasets.

first: Specifies the number of items to retrieve in a single page.
after: Indicates the cursor position to start fetching from. To get the first page, use null as the value, or simply leave the cursor empty (it defaults to the first page). Then, supply the last cursor from the previous response to retrieve the next page.

For information on GraphQL edge pagination, visit Pagination | GraphQL section.

Tip: Typename

When performing operations, some objects may not include a field that identifies their specific type in the output. To make these objects easier to identify, include __typename as a category label.

For example, if the query does not indicate whether an object is a customer, site, or organisation, adding __typename ensures the response includes the object type, making it easier to identify each node.

... on Site {
  id
  name
  parentOrganization {
    id
  }
  __typename
}

{
  "data": {
    "organizationSearch": {
      "nodes": [
        {
          "id": "1234-abcd-1234-abcd-1234",
          "name": "Site 01",
          "parentOrganization": {
            "id": "12345-abcde-12345-abcde-12345"
          },
          "__typename": "Site"
        }
      ]
    }
  }
}