Transitioning Queries to GraphQL: Overview

This guide outlines the simple, logical steps for transitioning your existing queries (from our REST, XML, or custom JSON endpoints) to our modern, unified GraphQL interface.

Our goal is a seamless transition that allows you to immediately benefit from improved performance and reduced data transfer.

Mapping Your Current Resources to GraphQL Types

The fundamental shift in GraphQL is moving from endpoints (like /api/v1/users) to structured Types.

Action Step: Review our Schema Documentation to see how your familiar resources are now defined as GraphQL Types.

Translating REST GET Operations to GraphQL Queries

GraphQL lets you retrieve only the data you need. In contrast, REST endpoints often return complete datasets, even if you only need a few fields. With our GraphQL API, you can specify exactly which fields to include in your response.

For example, suppose you need customer, device, and operating system details from N-central. In REST, you might need several queries to collect this information. With GraphQL, you can retrieve all of it in a single query.

In GraphQL, the query might look like this:

query GetAllNCentralDevices {
  assetSearch {
    totalCount
    nodes {
      id
      name
      customer { id name }
      operatingSystemInfo {
        name
        architecture
        type
      }
    }

   }
}

Advantages of GraphQL Queries

No Over-fetching: REST endpoints return all fields by default, such as address_id, status, and serial_number, even if you don’t need them. GraphQL returns only the fields you request, which makes responses smaller and faster.

Built-in Relationships: REST often requires extra calls, such as /dms/customer/{customerId} for customer details. GraphQL can nest related data, for example: customer { id name } This means you can retrieve related information in one query.

Translating Write Operations (POST/PUT/DELETE) to Mutations

Any write operation (create, update, delete) that you previously handled with REST (using POST, PUT, or DELETE) is translated into a GraphQL mutation. Instead of sending a payload to an endpoint, you pass a structured Input Object to a named mutation and specify what data you want returned.

REST vs GraphQL Formatting

This example mutation creates a new static tag in the system. Instead of sending a JSON payload to a REST endpoint, you pass an Input Object to the mutation and specify what fields you want returned.

• REST uses endpoint + HTTP verb + JSON body.

• GraphQL uses named mutation + structured input object + explicit return fields.

  REST format	GraphQL Mutation Format
  POST /api/v1/static-tag(...) with a JSON body	mutation CreateStaticTag(...)

The Migration Step:

1. 1. Identify the operation (e.g. "Create Static Tag").
2. 2. Use the corresponding Mutation name (e.g. staticTagCreate).
3. 3. Structure your payload data into the defined Input Type (e.g. staticTagCreate).
4. 4. Specify what data you want returned after the mutation succeeds (e.g., the new tag’s id). In the GraphQL example, the item block requests the id of the newly created tag, ensuring the client can reference it immediately after creation.

mutation staticTagCreate {
  staticTagCreate(input: {
    name: "Critical Systems",
    category: "Infrastructure",
    description: "Tag for critical infrastructure systems",
    organizationId: "ORG_ID_123"
  }) {
    item {
      id
      name
      category
      description
      organizationId
    }
    errors {
      code
      message
    }
  }
}

Where to Begin Your Transition

We recommend a staged, query-by-query approach to migration:

• Identify a Low-Volume Query: Start with a simple, read-only GET request from your current application that fetches minimal data.
• Translate and Test: Write the equivalent GraphQL query and run it against our new endpoint.
• Update Client Code: Modify your client-side code to issue the new GraphQL request and handle the JSON response.
• Repeat and Expand: Once successful, move on to more complex queries, especially those that benefit from nested data retrieval. Save your high-volume, performance-critical endpoints for later once you are comfortable.