The ultimate guide to graphQL

What is GraphQL?

GraphQL is a query language that makes it possible to write queries using an object structure rather than a text string. It is a powerful and flexible language that can be used instead of REST to work with APIs, that uses a simple declarative way to retrieve data.

• GraphQL processes queries such that you only receive the data you need. This eliminates the need to over-fetch or under-fetch data or filter large, complex objects.
• GraphQL lets you only use one request, rather than ping multiple endpoints to piece together your data.
• GraphQL handles the type-checking, where the types map onto Javascript objects.

It makes it possible to create massively improved APIs, that are cleaner, more performant, and easier to maintain. GraphQL lets developers write readable and concise queries, even when working with a complex database. It is being rapidly adopted by organizations large and small, that want to be able to work better with large datasets.

Unlike REST, GraphQL is a powerful and full-featured query language that is implemented through a set of tools on the server-side. These tools work by modeling the database as a graph. Objects are represented through nodes, and relationships are represented by edges on a graph. Then, when receiving a request the server-side tools use the graph structure to resolve queries and automatically retrieve the relevant data.

GraphQL can be used on top of a traditional database like Postgres, but Dgraph offers a native graph database that is designed to quickly handle GraphQL queries.

What problems does GraphQL solve?

To start with, GraphQL adds a layer of abstraction that makes APIs much more efficient and easier to work with. Using GraphQL means no more worrying about REST endpoints, which is especially useful when writing software that depends on a large or changing database.

As GraphQL uses server-side processing to resolve complex queries, less data needs to be sent back and forth compared to a REST API. This solves the problem of over-fetching, where an API call may end up returning much more data than is necessary, as well as under-fetching, forcing you to call a second endpoint. A smaller payload size for API calls can immediately make apps much faster and more efficient.

Not only is using GraphQL more efficient but it also generally means that less code needs to be written, which can make the codebase easier to maintain in the long run. The GraphQL language makes the API itself much cleaner and easier to maintain. It can cut the codebase size in half, as using the server-side resolver, what might have taken several calls with a REST API, can often be done in a single call with GraphQL.

Other language features, such use of strict typing, make the API easier to debug, as errors are easier to spot in GraphQL requests. GraphQL schemas are generally easy to read, being a strongly typed language. There is also support for automatic error handling. GraphQL resolves as much of the query as it can before returning, including information about any stacked queries that may have resulted in errors. This extra layer of abstraction makes it significantly cleaner to debug than a typical REST API.

Not only is using GraphQL more efficient but it also generally means that less code needs to be written, which can make the codebase easier to maintain in the long run. The GraphQL language makes the API itself much cleaner and easier to maintain. It can cut the codebase size in half, as using the server-side resolver, what might have taken several calls with a REST API, can often be done in a single call with GraphQL.

Why might I decide against using GraphQL?

The biggest disadvantage of using GraphQL is slowed performance for resolving large or complex queries. Compared to direct API calls, GraphQL imposes an additional time cost to process each request.

However, this issue is not as salient when using a native GraphQL database like Dgraph. Dgraph is able to handle millisecond query response times, even on deep queries with many layers of separation.

Additionally, some features such as file handling or caching might be better defined in REST APIs, and it might be an unnecessary hassle to switch to a fully GraphQL approach.

What apps can I build with GraphQL?

In general, GraphQL is most useful for making it easier to work with a large or complex database. It is most obviously used in data unification. Using GraphQL also allows for shorter and cleaner programs to be written, leading to a faster development cycle. It makes it possible to do agile development of apps that connect to an older database.

• In the enterprise, GraphQL can be used to upgrade the interface to an older database by quickly writing new apps. It has been used to deal with customer data, healthcare data, and analysis in financial services. GraphQL makes it easy for nested data to be fetched in a single call, which can make it easy to do data unification across multiple databases.
• For startups and small businesses, GraphQL can be especially useful as a part of a microservices architecture. Each database or service can handle the business logic and data for a single domain, and GraphQL can be used to bring them all together into a single service.

GraphQL is also especially useful when efficiency and speed matter for data retrieval, such as building apps for mobile, IoT, or wearables. For example, if an app involves notifications, you’ll want to use GraphQL subscrptions for real-time database pushes.

Because of the power and flexibility of GraphQL, you can use it to build everything ranging from a real-time chat application to a book review app, an Amazon-like recommendation engine or a Tinder clone.

Dgraph has built a variety of sample apps with GraphQL, so you can see the source code or tinker with the app for yourself.

See all our examples on Dgraph Learn

Dgraph is GraphQL native. How does that help me?

Dgraph is the most advanced native GraphQL database with a graph backend. This means Dgraph is not an interface on top of an existing database like Postgres but is actually designed from the ground-up for GraphQL. It is optimized for speed and performance, depending on multiple computer science breakthroughs to get the best result. But GraphQL was never designed to work as a database query language. Just like REST, the language describes the data to be fetched from an API. But unlike REST, a GraphQL request takes the shape of a graph, describing the data objects and the relationships among them. Because Dgraph is a graph database, a query language like GraphQL makes perfect sense. But you also need to keep in mind all the possible traversing users might need on their data. For that, you need something more robust than GraphQL. That’s why Dgraph introduced DQL—the Dgraph Query Language. A fork of GraphQL, it extends the basic GraphQL abilities to work as a powerful query language. DQL interacts directly with the database, enabling deep traversals and complex queries that aren’t possible in plain GraphQL, while also providing a spec-compliant GraphQL implementation thanks to the GraphQL-to-DQL layer that sits on top. That means you get native GraphQL executions, using the standard GraphQL that you’re already familiar with, without getting frustrated by problems seen in existing GraphQL solutions that Dgraph eliminates.

Why does GraphQL work best with a graph database?

Because GraphQL is implemented through a set of tools on the server-side that work by modeling the database as a graph. Just like in a graph database, objects are represented through nodes, and relationships are represented by edges on a graph. When receiving a request, the server-side tools use the graph structure to resolve queries and automatically retrieve the relevant data.

GraphQL works by resolving API requests through a query system. Graph databases like Dgraph are built like a search engine. Both the data and the queries are broken down into smaller, more manageable parts, that allow for the whole system to be fast and flexible, even at scale. This allows for blazingly fast GraphQL queries, even for layered queries and very large datasets.

What are the best GraphQL tools?

Every developer has an ideal tech stack that they use for most GraphQL projects. These include a database, a client, a means of front-end development, as well as a variety of tools to add functionality or improve performance. For example, you might use Dgraph (database), Apollo client (client), React (frontend), as well as Typescript (programming language) and GraphQL Code Generator (code checking).

The GraphQL ecosystem has a vibrant community of tools that can make the development experience smoother, and it is continually growing.

Several tools are designed to work with GraphQL, but there are also GraphQL-specific IDEs such as GraphiQL, GraphQL Playground, Insomnia, Altair, Postman, and Firecamp.

What do I need to get started with GraphQL?

You need a GraphQL endpoint and a GraphQL client. The endpoint can either be a server or a database. There are GraphQL clients that are widely adopted and supported, or you can use a popular language – most have a GraphQL client library.

Databases

The biggest disadvantage of using GraphQL is slowed performance for resolving large or complex queries. Compared to direct API calls, GraphQL imposes an additional time cost to process each request.

Servers

There are a wide variety of GraphQL servers to choose from. GraphQL.js the reference implementation of GraphQL, written in Javascript. The Apollo Server is one of the most commonly used servers for building APIs in GraphQL. Express-GraphQL is a library for creating a GraphQL HTTP server using Express.

Clients

GraphQL client is how the frontend makes requests to the server. The Relay GraphQL client is built and maintained by the creators of GraphQL. The Apollo Client is one of the best-known client-side libraries for GraphQL. urql is another GraphQL client by Formidable Labs, supporting multiple frontend frameworks.

Languages

GraphQL can be used with almost any language including Go, Ruby, and Clojure, as well as Javascript and Typescript.

Schema-first vs Code-first

The most common way to work with GraphQL is schema-first, which means writing a schema to represent the database, and creating software based around that. Dgraph also relies on schemas as part of the setup process. In code-first approaches, the developer writes the resolver functions first, and the code is used to generate a schema. It’s much more common for tools to support a schema-first approach.

How do I learn more about GraphQL with Dgraph?

To immediately see what Dgraph is about, you can check out the GraphQL or DQL tour.

Once you’re ready to start learning, you can check out our tutorials at Dgraph Learn, which will take you from GraphQL basics to building an app in less than four hours. You’ll learn how to create full-stack applications like a message-board app, in React and Vue, harnessing the power of Dgraph Cloud. Dgraph Cloud is a fully-managed GraphQL backend service.

From just the GraphQL schema, you get a fully functional GraphQL API ready to accept requests, without you going through the grunt work of writing resolvers or creating types on your own. Building on the Dgraph platform means you get a painless and enjoyable developer experience while building GraphQL applications.

If you’ve been working with SQL and want to explore what GraphQL and Dgraph can do for you, check out our course Dgraph for SQL users, where we examine SQL against GraphQL and see how our native GraphQL solutions can open ways to more opportunities for you.

Dip your toes into our docs for more resources and technical details on GraphQL, Dgraph Cloud, and more.

Be sure to browse through our blog, which contains regular updates on all topics related to graph databases and GraphQL.

Finally, join our vibrant community over at Discuss, where we’re accomplishing amazing things together. We’d be excited to have you.