February 16, 2021

What is GraphQL? GraphQL introduction

Khalil Stemmler
Developer Advocate
@stemmlerjs
BackendCommunityFrontend

In recent years, app development has become quite complex. Gone are the days of merely pulling some data from a database and displaying text on a page with a form.

Today, we call upon app developers to build rich, complex user interfaces and create memorable web experiences from a variety of different sources.

Unfortunately, traditional API styles like REST can become cumbersome to work with as complexity grows.

GraphQL is the modern approach to client-server communication and aims to improve the way developers build applications on the web.

In this post, we’ll learn about what GraphQL is, where it came from, how it works, and what benefits it has over traditional approaches to building and maintaining an API.

What is GraphQL

In essence,

GraphQL is a query language and a server-side runtime (typically served over HTTP).

Let’s break this down piece-by-piece.

GraphQL is a query language

While GraphQL has nothing to do with SQL (or any database), it is a query language.

The structured way in which we make requests presents two types of operations: queries and mutations.

Queries fetch data and are synonymous to GET calls in REST, while mutations signal that we’d like to invoke a change the in system, similar to REST’s POST or DELETE methods.

Learn more about the “Anatomy of a GraphQL Query” in this post by Sashko Stubailo.

Runtime

The runtime part points to the fact that a GraphQL API runs on a server.

In a GraphQL API, we shape our data within a strictly typed schema, telling it how to resolve data when asked for. To GraphQL, where data comes from doesn’t matter. It could be from a database, micro-service, or even an underlying RESTful API.

GraphQL is data source agnostic.

An image describing what is graphql

Served over HTTP

GraphQL is typically served over HTTP. This means operations are just plain ol’ strings, and we don’t need a special tool to query data from a GraphQL server.

A brief history

Facebook created GraphQL in 2012. They needed a better data-fetching approach that they could use across the entirety of the company’s products and services. They also wanted something that was understandable by developers, designers, as well as non-technical folk. After using it internally for some time, Facebook open-sourced GraphQL in 2015.

GraphQL makes it easier for app developers to get the data they need without needing to know which sources it’s coming from

How does it work?

Design your GraphQL schema

On the server, we create a GraphQL schema based on the data we need to build our app UIs. If we were building a job board, it’s here that we’d model out the Job, Company, and Location types.

Connect your resolvers to data sources

For each type, we write the resolver functions, connecting the data to our graph. Perhaps we get the Job data from an external API. And maybe we get the Location data from the Google Maps API.

Ask for exactly what you want

Finally, write your query, specifying precisely what you’d like to fetch. No more, no less.

Apollo Studio: GraphQL IDE
Here’s an example of a query using Apollo Studio’s Explorer. Like we used Postman for REST, Apollo Studio’s Explorer is a great way to build out and test your GraphQL APIs.

We recommend using a GraphQL client library like Apollo Client if you’re building apps with GraphQL. To see other approaches, check out “4 Simple Ways to Call a GraphQL API“.

Key features of GraphQL

Performance

Prevents over-fetching: In traditional approaches like REST, you often end up over-fetching — asking for more data than you need. With GraphQL, you can ask for exactly what you need. The benefit is reduced bandwidth, which may be especially important on mobile and low-energy devices.

Prevents under-fetching (multiple round-trips): The other end of the fetching problem in REST is not getting all the data you need in a single round-trip. Consider fetching your friends list in a social media app and needing to batch individual queries to get each friend’s profile picture. GraphQL helps solve this problem.

Developer experience

Hierarchical & declarative: GraphQL data is inherently graphical and declarative. This makes your queries easier to understand and your data easier to work with. By nesting, we can ask for related data, keeping queries cohesive, and spending zero time stitching together multiple responses like we sometimes have to do with REST.

Strongly typed (stable API): GraphQL is strongly typed. This means a more stable API with fewer bugs in development and introduces the possibility of more intelligent tooling.

GraphQL versioning: GraphQL favors the notion of a single, incrementally developed graph. You can give deprecation hints when you add, remove, and change fields on your existing graph. Compare this to the coarse-grained approach to versioning in a REST context with version numbers across an entire API.

Architecture

Decouples the client from the server: UI developers don’t need to wait for backend teams to build an API first. A GraphQL schema acts as a contract for front-end app devs to start building (by mocking out the API calls) and leaves backend teams to deliver on the contract by building the underlying services that serves the graph.

Single source of truth: UI developers only need to know about to a single endpoint to access the entirety of the data behind a company’s graph.

Scalable with Federation: GraphQL fits nicely into a microservice architecture using an approach called Federation. Federation enables backend teams to maintain their own sub-graphs and compose them into a single graph for an entire organization.

Introspection: This key feature lets you ask the GraphQL system what types of queries it supports. Introspection provides the framework for all kinds of great tooling. There exist tools to auto-generate API docs and TypeScript types for your resolvers and queries.

Community

Great tooling: We build tools for GraphQL developers. From GraphQL client libraries (like our very own Apollo Client), GraphQL IDEs (Apollo Studio), and GraphQL servers (Apollo Server), you’re likely to modern tooling in a variety of languages. There are also a wide range of mature community-built tools for you to try out.

Widespread adoption: GraphQL is currently being used by a large number of notable companies including GitHub, PayPal, Glassdoor, Shopify, Twitter, The New York Times, Expedia, etc.

Challenges & considerations

When GraphQL was first released, major topic areas like caching, query complexity, and security were major concerns in the community.

Over the years as GraphQL and the larger community around it matured, we’ve identified common solutions and best practices to the majority of these problem areas.

Conclusion

  • GraphQL is a query language and a server runtime that typically runs over HTTP
  • It was designed to be more efficient, performant, and provide a better developer experience for working with data in a client-server architecture
  • GraphQL adoption has significantly grown since it was first open-sourced and it doesn’t look like it’s going anywhere soon.

What next?

I’m a believer of “if we do it, we know it”. If you’re just getting started with GraphQL, I highly recommend you check out our completely free “Lift Off” GraphQL course.

In less than 30 minutes, you’ll learn the core components of a full-stack GraphQL app with Apollo through an interactive tutorial.

You can get started here. Enjoy!

Written by

Khalil Stemmler

Follow

Developer Advocate at Apollo GraphQL ⚡ Author of solidbook.io ⚡ Advanced TypeScript & DDD at khalilstemmler.com

Read more by Khalil Stemmler

Stay in our orbit!

Become an Apollo insider and get first access to new features, best practices, and community events. Oh, and no junk mail. Ever.

Make this article better!

Was this post helpful? Have suggestions? Consider so we can improve it for future readers ✨.

Similar posts

April 6, 2021

Unblocking teams to go faster with Apollo Federation

by Matt DeBergalis

Company