A Brief Tutorial on GraphQL

GraphQL is the main interface to interact with Infrahub. As such, I thought it would be helpful to give an introduction to those who are less familiar. GraphQL is a relatively new method for creating APIs that offers advantages in efficiency, error handling, and backward compatibility compared to REST. GraphQL provides a great alternative to REST in use cases where the need to deal with complexity in data exchanges outstrips the need for simplicity in the API.

Infrahub is designed to enable infrastructure teams to create consumable services from whatever infrastructure they’re managing. As such, Infrahub employs a completely customizable schema to combine diverse data such as service models, asset management, configuration management data, etc.

For example, suppose you’re building a new AI data center filled with super-expensive GPUs, and you want to turn that data center into a fully automated service where you can update use cases and automate configuration changes so you don’t suffer any downtime of all that capital. In that case, this is an example of what the Infrahub project is meant to make possible. That involves combining disparate data, creating a complex data management challenge. As a result, the project uses a graph database (a technology different from GraphQL), which allows for a ton of schema flexibility.

GraphQL comes into play because you need tremendous flexibility to exchange data with this graph database built custom to every deployment. GraphQL provides flexibility and efficiency to make it possible to automate large-scale infrastructures promptly. Working on Infrahub has illustrated the power of GraphQL to me in a way that I wouldn’t have grasped as thoroughly before.

GraphQL Origins and History

GraphQL was initially created and used internally by Facebook in 2012 while developing the News Feed section of their IOS application. In 2015, it was released as an open source project, and in 2018, the project was moved from Facebook to the GraphQL Foundation, which the Linux Foundation hosts.

GraphQL and REST are complementary and share common API architecture characteristics. Both use a client-server model with stateless servers and communicate via HTTP. They both support similar data formats, such as JSON, and can work with any database and programming language.

Limitations in REST That GraphQL Is Designed To Solve

The main reason for GraphQL’s development at Facebook was to overcome the challenge that REST-based APIs were too lengthy and rigid to produce news feeds efficiently. While this was the origin use case, GraphQL brings advantages for any API use case requiring high volume, variable, and complex data interactions.

Limitations of REST that GraphQL addresses:

• Fixed structures for data exchange and over fetching: REST APIs use pre-defined data structures for exchanging data. This simplifies things, but even if you need one piece of data from a data structure, you must always receive the whole thing.
• Multiple endpoints for different data resources and under fetching: If you need two different types of data, you need numerous REST API requests.
• Weak data typing and limited error checking: REST data does not enforce typing, meaning the client must figure out how to interpret the formatted data when returned. In addition, weak typing makes error checking more difficult and leaves it to the client. This is fine with simple data sources where resources are easily defined. Still, in cases with complex data sources, this ambiguity and difficulty in error handling is a significant disadvantage.

How GraphQL Solves These Limitations

Where REST is a set of rules to define structured data exchange between a client and a server, GraphQL encompasses a query language, schema-driven architecture, and tools.

• Mandatory schema: GraphQL defines a schema for queries.
• Single URL endpoint: GraphQL utilizes a single URL endpoint for all data exchanges rather than separate URLs for different resources.
• Flexible, client-defined data exchanges: Unlike REST, where you request a resource and get all of it whether you want it or not, GraphQL allows you to create flexible and precise queries to fetch just the data you want.
• Strong typing: GraphQL data is strongly typed, so the client will continuously receive data in a predefined format that is well understood.
• Error handling: Due to its predefined schema and strong data typing, invalid requests can be elegantly rejected, and an automated error message can be served.

GraphQL Is Powerful for Complex Data Exchanges

When you need to execute complex data exchanges across multiple data sources and where there may be a high degree of variability in client requests, GraphQL offers an efficiency advantage regarding the number of queries needed and the amount of data fetched. These complex use cases also benefit from better data typing and error checking, which are available in GraphQL.

Here are some general examples of where GraphQL brings advantages to data exchanges:

• For mobile applications where bandwidth constraints mean that multiple queries to fetch required data are undesirable, GraphQL can help by batching multiple requests together into a single query across the network.
• In situations involving a collection of newer and legacy systems, there may be a need to query multiple sources to get the required data. GraphQL provides more control over how that data is obtained.
• Aggregating APIs also benefits. GraphQL allows teams to combine multiple APIs into a single API endpoint, simplifying API versioning.
• GraphQL helps with fetching nested data. Sometimes, queries require fetching primary and related nested data sets. An example is fetching blog posts and associated comments.
• Finally, GraphQL is useful for querying network and infrastructure automation data. Service delivery across networks and other complex IT infrastructure involves multiple devices related by topology or other relationships. GraphQL makes it easier to fetch configuration or state data from a series of linked data objects for monitoring, security, and auditing purposes.

GraphQL offers significant flexibility and efficiency benefits to API data transfers with greater complexity, variability, latency, or bandwidth constraints. While REST remains the default API for many applications, GraphQL is a powerful option in the API developer’s toolkit.

If you want to learn more about GraphQL in the context of Infrahub, read more in our documentation. If you’re intrigued to try Infrahub, check out our Github. Or if you know you’d like to get started on turning your infrastructure into services, request a demo.