Frequently Asked Questions
Common questions asked at each stage of GraphQL adoption
Everyone has questions about how to properly set up a GraphQL schema, but not all questions are alike. In different stages of development, different things matter. This guide answers questions that people commonly have at every step along the journey to GraphQL in production.
You're just getting started with GraphQL. You're learning about syntax, running queries, schemas, and how to connect your existing services to your GraphQL layer.
GraphQL is a language for querying data. With GraphQL, your existing services describe the data that they have, and clients describe the data they need. This is possible because of a strongly-typed schema (type definitions).
GraphQL can make a difference in nearly every area of development: from improving developer experience with quality tooling to improving client performance by reducing bundle sizes. Read more about the benefits of GraphQL.
Apollo's learning platform, Odyssey, provides practical, hands-on courses that help you learn GraphQL with Apollo technologies.
This documentation also includes a full-stack tutorial and getting-started content for each platform component:
For an introduction to core GraphQL concepts, check out graphql.org.
For technical GraphQL content from Apollo developer advocates and the larger GraphQL community, check out the Apollo blog.
GraphQL servers created with
apollo-server can be deployed to any environment that supports Node.js projects can be deployed.
apollo-server even has variants to support serverless deployment with AWS Lambda.
There are deployment guides available for:
The Apollo platform has tools available to connect almost any kind of client to your schema:
- Apollo iOS for native iOS clients
- Apollo Android for native Android clients
You understand how GraphQL works and the benefits it offers. You're trying to create a proof of concept for your project or company to test GraphQL's viability in production.
One of the best things about GraphQL is that it works excellently with existing APIs. It's possible to connect any number of existing services to your schema.
The most common source is a REST API. The
RESTDataSource is a tool that integrates with
apollo-server to simplify fetching and caching for existing REST APIs.
Other DataSources are under development, but even without the
DataSource API, it's possible to connect any backend to a schema. Resolvers can do anything, including fetch data from an SDK or ORM.
Schemas should be designed with the needs of the client 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 makes it possible to allow this flexibility without many performance consequences. For more, read the schema design guide.
As with any service, it's important to track errors and their causes. There are many kinds of errors that can occur with a GraphQL Schema. Some of these include service errors, where the schema can't access underlying services, and user errors, where a user enters invalid information in a query or mutation.
GraphQL is resilient to some of these errors. Since the schema is strongly typed, the designer has the ability to restrict what type of data users can enter and what type the 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. Apollo Studio is a tool that does exactly this. It can help discover and reproduce errors by showing the exact conditions in which the error occurred.
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 it and monitor it in production.
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.
GraphQL schemas work best when their design is heavily influenced by the needs of the product developers. It's tempting to design a schema to resemble the underlying sources or databases, but this can reduce the usefulness of GraphQL.
Authentication and authorization are important topics to discuss with any API. GraphQL provides a very 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.
Public APIs of any kind need some kind of safeguards against malicious queries. Since GraphQL allows for recursive queries, it wouldn't be hard to create a query that is overly complicated and acts as a DoS attack, even by accident. There are multiple ways to prevent something like this from happening, from complexity limiting to query depth limiting. Read the guide on security to learn more.
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 movies, each movie is cached separately on the client. Later, if the client requests a single movie in a different query and the needed movie 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. Regardless of whether the API is used for public data or not, these caches almost always provide large performance benefits and are highly recommended. You can read more about how to set up whole-query and CDN caching with
apollo-server 2.0 here.
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.
Many apps and sites are powered almost completely by an API such as a GraphQL schema, so it's important to make sure the API is healthy at all times. Indicators of an unhealthy service include long response times, high resource usage, and unusual traffic patterns.
Apollo Studio is a great tool to track many of these things. It allows close inspection of fields to make it easy to see both total response times as well as how long each field took to execute.
Apollo Studio also has some integrations to make monitoring easier. The Slack Integration delivers daily reports to give teams a quick overview of the health of their schema. The Datadog integration) works with existing Datadog accounts, to help teams track schema performance.
You have a good understanding of how to write, deploy, and monitor GraphQL in production. You are looking to scale GraphQL features to your entire product line.
Keeping all schema code together makes sense for smaller projects, but once a project reaches a certain size, or has many people working on it, managing conflicts in the same file and code navigation can get difficult. Splitting types and resolvers up into smaller files can make this process much easier. Read this blog post to learn more.
react-apollo comes with everything needed to test a client app that makes queries to a GraphQL schema. Read the Testing React Components guide to learn more.
Schemas naturally evolve over time. GraphQL schemas are more resilient to change than other APIs, but there are still occasions where breaking changes will need to happen to support new functionality. The versioning guide explains in more detail what kinds of changes are safe to make, and what kinds could break existing clients.