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.

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. Use null for the first page, then supply the last cursor from the previous response to get the next page.

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

Error Handling

GraphQL provides detailed error messages that make debugging easier and more transparent. One of its key advantages is support for partial success - even if part of a query fails, the rest can still return valid data. Unlike REST, GraphQL errors are not tied to HTTP status codes, allowing for more nuanced and informative responses directly within the API payload.

For information on common errors in  GraphQL and how to debug them, visit GraphQL.org's Common HTTP Errors and How to Debug Them section.