GraphQL Basics for Network Engineers: A Practical Introduction

Technical

May 9, 2025
By Pete Crocker

As networks become increasingly programmable and API-driven, it’s no longer enough for network engineers to just understand CLI and SNMP. Whether you’re working with SD-WAN, cloud networking, or network observability tools, chances are you’ll encounter GraphQL.

Unlike traditional REST APIs, GraphQL gives you fine-grained control over the data you retrieve or modify—something that’s incredibly handy when dealing with complex network topologies or massive telemetry datasets.

This overview of GraphQL basics is specifically designed for beginners. In it, I’ll explain:

What GraphQL is and why it’s helpful to know as a network engineer
GraphQL vs REST API and how the two are different
How to perform a GraphQL query and a GraphQL mutation, as well as work with GraphQL filters

Why Network Engineers Should Care About GraphQL

Let’s start right at the beginning: What is GraphQL and why is it important to someone managing infrastructure data?

GraphQL is a query language for APIs developed by Facebook and now maintained by the GraphQL Foundation. Instead of hitting multiple endpoints like you often do with the REST API, GraphQL lets you send one query to get exactly the data you want—no more, no less.

Network and infrastructure platforms like Cisco DNA Center and Juniper Apstra offer GraphQL APIs, and so does Infrahub. That means if you know how to use GraphQL, you can extract precise data for automation scripts, dashboards, and troubleshooting workflows much more efficiently.

Benefits of GraphQL

Reduce over-fetching: Avoid downloading full device objects just to get a hostname.
Simplify scripting: One request can replace several chained REST calls.
Improve performance: Especially useful for webhooks, alerts, or large-scale telemetry.

GraphQL vs REST API: Key Differences

Let’s quickly compare the two so you understand why GraphQL can be more helpful than the REST API in some scenarios.

Feature	GraphQL	REST
Endpoint model	Single endpoint	Multiple endpoints
Data retrieval	Client specifies structure	Fixed structure per resource
Over-fetching	Minimal (client-define)	Common
Under-fetching	Rare	Common
Tooling	Rapidly growing	Mature and broad

GraphQL is very tightly coupled with the idea of a schema. It has no standard way for structuring objects, drawing instead on whatever data schema you build.

If you have a schema with 10 different objects, for example, you’ll have to make 10 different queries to the REST API. But in GraphQL, you could query all 10 object types at the same time.

Example Scenario
Suppose you’re querying interface stats on a router. In REST, you might:

Call /devices to get device IDs.
Call /devices/{id}/interfaces for interface IDs.
Call /interfaces/{id}/statsfor each interface.

In GraphQL, you’d write one query and get just the fields you want—say, name, status, and.

How to Perform a GraphQL Query

A GraphQL query is structured and explicit. You describe what you want, not how to get it. Here’s a basic example to get interface names and their status:

				
					graphql
{
  devices {
    name
    interfaces {
      name
      status
    }
  }
}

This is equivalent to several REST calls rolled into one, with less noise in the response.

Things to note:

The query starts with {} instead of a verb like GET.
You only ask for the fields you care about.
The structure of the response matches the structure of the query.

You typically send these queries via HTTP POST to the GraphQL API endpoint, often named something like /graphql.

Using Filters in a GraphQL Query

GraphQL queries become powerful when you add arguments (like filters). These let you zero in on specific resources, just like query parameters in REST.

Example: Get only interfaces with status = "down":

				
					console.log( 'Code is Poetry' `graphql
{
  devices {
    name
    interfaces(status: "down") {
      name
      status
    }
  }
}

Some GraphQL APIs also support more complex filtering (e.g., ranges, regex, nested filters), depending on the schema. That means you can write expressive, highly targeted queries without post-processing the results in your script.

Working With GraphQL Mutations

While queries read data, mutations change it—like updating a config or triggering a workflow.

Here’s a basic mutation that sets an interface’s description:

				
					graphql
mutation {
  updateInterface(id: "eth0", input: { description: "Uplink to core" }) {
    id
    description
  }
}

Key differences between GraphQL mutations and queries

You must use the mutation keyword.
Input arguments are often wrapped in an input object.
The response still shows only the fields you request—great for confirmation and debugging.

This pattern is ideal for config automation tools and interactive dashboards, letting you modify resources while keeping the response lightweight.

Using GraphQL in Infrahub

You’ll recall when we talked about the difference between GraphQL and the REST API, that one of the defining features of GraphQL is that it’s defined by whatever schema you’re working with.

Since Infrahub also works on whatever custom schema you give it, that means every object that’s already part of your Infrahub schema is available to query with GraphQL. In fact, GraphQL is what Infrahub uses as its query engine to give you fine-grained and powerful control of your infrastructure data.

The syntax for working in GraphQL in Infrahub is a little different than the standard syntax we’ve been using so far in this post. For example, here’s the GraphQL mutation to set an interface description you would use in Infrahub.

				
					graphql
mutation {
  InfraInterfaceL3Update(
    data: {
      hfid: ["atl1-edge2", "Ethernet1"]
      description: { value: "My updated interface description" }
    }
  ) {
    ok
    object {
      id
      hfid
      name {
        value
      }
      description {
        value
      }
    }
  }
}

You can learn more about the GraphQL basics in Infrahub in the video below, as our CEO and co-founder Damien Garros walks you through a query, a bit of filtering, and how mutations work from the Infrahub interface.

Damien is using the Infrahub sandbox in this demonstration, which is free to access, so you can follow along and try some of the examples yourself.

Wrapping Up

GraphQL’s structure and clarity make it a valuable tool for engineers working with API-driven network systems. By understanding the basics of queries, filters, and mutations, you’ll be better equipped to extract and act on the exact data you need, without unnecessary complexity.

The bottom line? Getting comfortable with GraphQL can save you dozens of lines of code—and hours of frustration.

Helpful Resources

Infrahub GraphQL documentation
Experiment with GraphQL in the free Infrahub Sandbox

Share the Post: