Join us on Nov 7 for GraphQL Summit Virtual

Join API innovators, GraphQL experts, and AI trailblazers on Nov 7 at GraphQL Summit Virtual. Register for free →

GraphQL.com

LearnTutorialsCommunityEvents

Table of contents

    GRAPHQL BASICS

  • What is GraphQL?
  • The Query
  • Introducing Types
  • Scalars, Objects, and Lists
  • Nullability
  • Querying between Types
  • Schema
  • Enums
  • Interfaces & Unions
  • Arguments
  • Mutations
  • FAQBuilding a proof of conceptMoving to productionMigrating a feature to GraphQLMigrating a product to GraphQL


Try GraphOS  
The GraphQL developer platform

FAQ

This article answers common questions about GraphQL, organized by phases in the GraphQL adoption timeline.

Building a proof of concept

After reading through the GraphQL basics, you understand how GraphQL works and its benefits. You're trying to create a proof of concept for your project or company to test GraphQL's viability in production.

Which language should I use for my GraphQL server?

If you need a refresher on GraphQL servers, check out How does a GraphQL server work?

There are GraphQL server tools available for most popular languages. Use the one(s) that best fit with your existing stack. If you plan on using a federated architecture, check out the list of federation-compatible server libraries.

How do I wrap existing APIs?

One of the best things about GraphQL is that it works excellently with existing APIs. You can connect any number of existing services to your schema.

The most common source is a REST API. In the Apollo Server library, for example, the RESTDataSource class integrates with Apollo Server to simplify fetching and caching for existing REST APIs. However, you can connect any backend to a schema. Resolvers can do anything, including fetch data from an SDK or ORM.

Many federation-compatible server libraries offer similar capabilities.

How do I design the schema?

Schemas should be designed with the client's needs in mind. Rather than modeling queries and types after the underlying services, they should be designed to make querying as easy as possible. GraphQL's resolver structure allows this flexibility without many performance consequences.

How do I connect my client app to my schema?

The GraphQL community offers a rich ecosystem of client tooling. Apollo provides the following open-source, industry-standard SDKs:

  • Apollo Client for JavaScript clients
  • Apollo iOS for native iOS clients
  • Apollo Kotlin for native Android clients

How do I discover and reproduce errors?

As with any service, tracking errors and their causes is important. Many kinds of errors can occur in a GraphQL implementation. Some of these include service errors, where the schema can't access underlying data sources, and user errors, where a user enters invalid information in a query or mutation.

GraphQL is resilient to some of these errors. Because the schema is strongly typed, you can restrict what types of data users can provide as input, along with what types your resolvers can return. This type system catches many errors and requires no manual checks.

For errors not prevented by the type system, it's helpful to know what exact queries were made and with what variables. The Apollo GraphOS platform includes analytics tooling that does exactly this. It can help discover and reproduce errors by showing the exact conditions in which the error occurred.

Moving to production

After a successful proof of concept, the next step is to ensure your GraphQL service is ready for the demands of a production environment.

How can I secure my schema from malicious or expensive queries?

Public APIs of any kind need some safeguards against malicious queries. Since GraphQL allows for recursive queries, it wouldn't be hard to create an overly complicated query that acts as a DoS attack, even by accident. There are multiple ways to prevent something like this, from complexity limiting to query depth limiting. Read Apollo's security blog post to learn more.

How do I set up authentication/authorization for my GraphQL schema?

Authentication and authorization are important topics to discuss with any API. GraphQL provides a granular approach to handling these topics. But don't worry; if an API being consumed by GraphQL already has authorization built-in, it may be possible to ignore it completely.

What kinds of caching should I set up?

GraphQL can be cached in multiple places.

On the client, caches can prevent multiple queries from being called when data is already available locally. Client caches for GraphQL have one significant advantage over REST client caches: they can handle queries that have never been made. This is possible because of how GraphQL responses are normalized and stored.

For example, if a client requests a list of fruits, each fruit is cached separately on the client. Later, if the client requests a single fruit in a different query and the needed fruit is in the cache, the request doesn't have to use the network. This normalized cache is a part of apollo-client by default.

You can also set up server-side caching, including whole-query caching, partial-query caching, and cache backed by a CDN. These can lower response times and make your GraphQL server as performant as possible.

Whole-query and CDN caches are most useful when an API handles multiple identical queries. This commonly happens with public data, like content on pages of a site. Whether the API is used for public data or not, these caches almost always provide large performance benefits and are highly recommended. See Server-side caching to learn about whole-query and CDN caching with Apollo Server.

Partial query caching can be achieved by caching the responses from underlying services with something like Redis or Memcache. With this strategy, even if two queries look completely different from one another, if there is any duplication of data fetched, those results can be shared, preventing unnecessary traffic. The RESTDataSource does this automatically if the appropriate cache-control headers are present in REST responses.

How can I monitor the health of my GraphQL service?

Many apps and sites are powered almost completely by an API such as a GraphQL schema, so it's important to ensure your service is always stable. Indicators of an unhealthy service include long response times, high resource usage, and unusual traffic patterns.

GraphOS Studio is a great tool for tracking many of these things. It allows close inspection of fields, making it easy to see total response times and how long each field took to execute.

GraphOS Studio also has some integrations to make monitoring easier. Notifications can deliver daily reports to give teams a quick overview of graph's health. The Datadog integration works with existing Datadog accounts to help teams track schema performance. Finally, you can configure the GraphOS Router to export telemetry metrics to your APM of choice.

Migrating a feature to GraphQL

You've decided to use GraphQL in production. You don't want to immediately refactor the APIs or apps. You want to move a single feature over to GraphQL to learn how to use and monitor it in production.

How should the transition to GraphQL happen?

As with any large change, the adoption of GraphQL should be incremental. GraphQL allows teams to leave existing services as they are and build convenient gateways on top of them.

Who owns the schema design?

GraphQL schemas work best when their design is collaborated on by the combination of backend implementers and frontend consumers. It's tempting to design a schema to mirror underlying API structures or database tables, but this can reduce the usefulness of GraphQL.

Migrating a product to GraphQL

You understand how to write, deploy, and monitor GraphQL in production and are looking to scale Its features to your entire product line.

How do I organize schema code to scale for a larger project?

Keeping all schema code together makes sense for smaller projects. However, once a project reaches a certain size or has many people working on it, it can be difficult to manage conflicts in the same file and code navigation.

This is when a federated architecture becomes imperative for scaling. Federation lets API teams operate in a microservices architecture while exposing a unified GraphQL API to clients.

Check out What is Federated Architecture to learn more.

How can I safely make changes to my schema?

Schemas naturally evolve over time. GraphQL schemas are more resilient to change than other APIs, but there are still occasions where breaking changes are necessary to support new functionality. GraphOS offers a suite of schema governance features, including schema checks, linting, and proposals, that let you manage, validate, and enforce standards in your schemas.

About

GraphQL.com is maintained by the Apollo team. Our goal is to give developers and technical leaders the tools they need to understand and adopt GraphQL.


GraphQL.com 2024