Frequently Asked Questions (FAQ)

Why should I use GraphQL?#

It depends on your use case, but in general, GraphQL has a few key features that stand out. For example, GraphQL enables you to:

• Aggregate data from multiple UI components.
• Create a representation of your data that feels familiar and natural (a graph).
• Ensure that all of your data is statically typed and these types inform what queries the schema supports.
• Reduce the need for breaking changes, but utilize a built-in mechanism for deprecations when you need to.
• Access to a powerful tooling ecosystem with GUIs, editor integrations, code generation, linting, analytics, and more.

Our homepage outlines even more reasons to use GraphQL.

You can try out GraphQL without rewriting your entire application. For instance, starting with a single HTTP request that wraps an existing REST call. Your GraphQL schema and business domain model can expand gradually. We recommend focusing on one use case at first and only building the part of the schema needed for that.

Does GraphQL replace REST?#

No, not necessarily. They both handle APIs and can serve similar purposes from a business perspective. GraphQL is often considered an alternative to REST, but it’s not a definitive replacement.

GraphQL and REST can actually co-exist in your stack. For example, you can abstract REST APIs behind a GraphQL server. This can be done by masking your REST endpoint into a GraphQL endpoint using root resolvers.

For an opinionated perspective on how GraphQL compares to REST, check out How To GraphQL.

Is GraphQL a database language like SQL?#

No, but this is a common misconception.

GraphQL is a specification typically used for remote client-server communications. Unlike SQL, GraphQL is agnostic to the data source(s) used to retrieve data and persist changes. Accessing and manipulating data is performed with arbitrary functions called resolvers. GraphQL coordinates and aggregates the data from these resolver functions, then returns the result to the client. Generally, these resolver functions should delegate to a business logic layer responsible for communicating with the various underlying data sources. These data sources could be remote APIs, databases, local cache, and nearly anything else your programming language can access.

For more information on how to get GraphQL to interact with your database, check out our documentation on resolvers.

How can I learn GraphQL?#

There are many resources available to help you learn GraphQL, including this website. In our documentation, you’ll find a series of articles that explain essential GraphQL concepts and how they work. Our Community page is full of resources to reference and groups to join.

For more practical guides, visit the How to GraphQL fullstack tutorial website. We also have a free online course with edX, Exploring GraphQL: A Query Language for APIs.

Before you start your learning journey, make sure you know what an API is and how communication generally works between client and server.

Is GraphQL only for React or JavaScript developers?#

No, not at all. GraphQL is a specification that can be implemented in any language. Our Code page contains a long list of libraries in many different programming languages to help with that.

It’s understandable why you’d think this, though. GraphQL was introduced at a React conference and GraphQL.js is one of the most widely used implementations to date. We know this can be confusing, so we’re working to improve our documentation and add more code samples that aren’t written in JavaScript.

Is GraphQL frontend or backend?#

Both. GraphQL specifies how you can exchange information between client and server. This includes how the server can indicate what data and operations are available, how the client should format requests, how the server should execute these queries, and what the client will receive in response.

Does GraphQL use HTTP?#

Yes, GraphQL is typically served over HTTP. This is largely due to how pervasive the HTTP protocol is in our industry. But it helps that you can try out GraphQL by creating a single HTTP request. Guidelines for setting up a GraphQL server to operate over HTTP are available in our Serving over HTTP documentation.

While HTTP is the most common choice for client-server protocol, it’s not the only one. GraphQL is agnostic to the transport layer. So, for example, you could use WebSockets for GraphQL subscriptions instead of HTTP to consume realtime data.

How does GraphQL affect my product’s performance?#

On a typical GraphQL backend, every field on every type has a focused, single-purpose function for resolving that value. Also, instead of trying to handle data batching on the client, GraphQL moves that logic to the server. As a result, there are some inherent performance benefits. Minimizing over-fetching and making fewer roundtrips to the server are two of them.

Other performance factors should be considered when building out your GraphQL implementation. For example, it’s possible for a GraphQL service to be ‘chatty’ and repeatedly load data from your database. This is commonly solved by implementing a batching technique or utilizing a tool like DataLoader.

What is a GraphQL client and why would I use one?#

GraphQL clients can help you handle queries, mutations, and subscriptions to a GraphQL server. They use the underlying structure of a GraphQL API to automate certain processes. This includes batching, UI updates, build-time schema validation, and more.

A list of GraphQL clients in various languages is available on our Code page. There’s also an in-depth explanation of their benefits on How To GraphQL.

You don't need a specific client to work with GraphQL, though. You might want to start out by issuing GraphQL results with a regular HTTP client. Then later switch to a GraphQL-optimized client as your application grows in complexity.

Does GraphQL replace ORMs?#

No, GraphQL is a specification typically used for remote client-server communications. It's agnostic to the data source(s) used and doesn’t implement an object-relational mapping technique. But there are ORMs built specifically for GraphQL. A few of those are listed under the Services section of our Code page.

Is GraphQL owned by Facebook?#

No, GraphQL is governed by the GraphQL Foundation.

That said, the specification was originally developed at Facebook and Facebook is a member of the GraphQL Foundation. You might notice that some of our GitHub repositories still have the license listed under Facebook Inc. We're updating those and have already converted major projects, like GraphiQL and DataLoader, to the the new copyright: "Copyright (c) 2020 GraphQL Contributors."

Who is behind GraphQL?#

Many people! The GraphQL specification and all related projects are open source, so anyone is welcome to contribute. That said, there is a structure in place behind the repositories. This exists to resolve conflicts within the community and guiding technical decisions.

The GraphQL Foundation provides most of the oversight for GraphQL. It's made up of representatives from dozens of different companies.

There are also monthly virtual GraphQL Working Group (WG) meetings managed by the GraphQL Foundation. These meetings are designed to bring together maintainers of commonly used GraphQL libraries and tools, as well as significant contributors to the GraphQL community. The WG meetings are completely open. Anyone is able to join and propose items to the agenda.

In the November 2020 WG meeting, it was announced that GraphQL will have a Technical Steering Committee (TSC) going forward. More on that coming soon.

If this is confusing, don’t worry - there’s a lot going on. To get a more visual, high-level overview, check out the GraphQL Landscape.

What is the GraphQL Foundation?#

The GraphQL Foundation is a neutral foundation that provides governance for GraphQL. This includes vendor-neutral oversight of open-source repositories, funding, events, and more. It's hosted under the Linux Foundation and consists of representatives from dozens of different companies. The idea is that it’s an impartial and open home for the GraphQL community.

You can find out more by visiting foundation.graphql.org.

Is GraphQL scalable?#

Yes, GraphQL is designed to be scalable and is used by many companies in production under a very high load.

GraphQL comes with some built-in performance boosts that can help. But once you push it to production, you're responsible for scaling it across instances and monitoring performance.

Does GraphQL support offline usage?#

No, or at least not natively. But there are GraphQL clients that enable you to build offline-first. They use features designed to perform data operations while offline, such as caching and service workers.

You can find a list of GraphQL clients in various languages on our Code page.

What are the security concerns with GraphQL?#

Most of the security concerns associated with GraphQL are typical for any API or service. A few examples: SQL injections, Denial of Service (DoS) attacks, or someone abusing flawed authentication. But there are also some attacks specific to GraphQL. For instance, batching attacks. These attacks can happen as a result of GraphQL allowing you to batch multiple queries (or requests for multiple object instances) in a single network call.

No matter the concern, it’s important to be proactive. There are many ways to securing your GraphQL server. Using a timeout, setting a maximum depth for queries, and throttling queries based on the server time it needs to complete are all potential approaches.

For an overview of common security concerns and how to address them, check out the Security tutorial on How to GraphQL and OWASP’s GraphQL Cheat Sheet.

How can I set up authorization with GraphQL?#

We recommend enforcing authorization behavior in the business logic layer. That way, you have a single source of truth for authorization.

For a more detailed explanation, go to our Authorization documentation.

How does authentication work with GraphQL?#

You can implement authentication with common patterns, such as OAuth or JWT. There’s nothing special about authentication within the GraphQL specification.

Some GraphQL libraries include a specific protocol for authentication as well. Although if you’re working with a pipeline model, we recommend that GraphQL be placed after all authentication middleware.

If you’re using GraphQL.js to build your API server, we have documentation on handling authentication with Express middleware.

Is GraphQL the right fit for designing a microservice architecture?#

Yes, it can be. If you’re integrating GraphQL into your microservice architecture, we’d recommend having one GraphQL schema as an API gateway rather than having your client talk to multiple GraphQL services. This way, you can split your backend into microservices, but then still aggregate all your data to the frontend from a single API.

There are many ways to create an API gateway. The benefit of using GraphQL is that you can take advantage of features like caching, request budgeting, and planning out query schedules.

How does versioning work in GraphQL?#

There’s nothing that will prevent a GraphQL service from being versioned like any other REST API. That said, GraphQL avoids versioning by design.

Instead, GraphQL provides the tools to continually build and evolve your schema. For example, GraphQL only returns the data that’s explicitly requested. This means that you can add new features (and all the associated types and fields) without creating a breaking change or bloating results for existing queries.

You can read more about how versioning works in GraphQL in our Best Practices section.

How can I document my GraphQL API?#

One of the benefits of GraphQL is that it's inherently self-documenting. This means that when you use an interactive tool like GraphiQL, you’re able to explore what data is exposed by your GraphQL API. This includes the fields, types, and more. You can also add a description field to provide supplementary notes about your endpoint. This description field supports strings and Markdown.

For many, this provides enough API reference documentation. But it doesn’t reduce the need for other forms of documentation. You'll likely still need to create guides that explain how the general concepts tie into your specific use case.

What is the best way to follow specification releases?#

The latest working draft release of the GraphQL specification can be found at spec.graphql.org/draft. Previous editions are also available at permalinks that match their release tag.

The entire process behind each release is open source. You can monitor specification proposals by following pull requests in the graphql-spec repository. You can also watch past GraphQL Working Group discussions about various proposals on YouTube.

How can I contribute to the GraphQL specification?#

GraphQL is still evolving and contributions are very welcome! The specification (including the latest working draft) is open source. Contributor guidelines are available on GitHub.

There are more ways to get involved with GraphQL beyond the specification though. Updating the content on this website and the documentation, for example. Or contributing to graphql-js, graphql-http, GraphiQL, or one of the many other projects maintained by the GraphQL Foundation.

What is GraphQL Specification membership?#

The GraphQL Specification and the associated reference implementations are a Joint Development Foundation project (also part of the Linux Foundation family). Individual or corporate contributors sign a document at no cost that they agree their contributions are under the open source licenses of the project. Because this is not GraphQL Foundation membership, specification members do not decide how to spend the budget.

To sign the GraphQL Specification membership document, open a PR against any GraphQL repo on GitHub.

If your organization uses and benefits from GraphQL, please consider becoming a member of both by opening a PR on behalf of your company and joining the GraphQL Foundation.

Where is the documentation for subscriptions?#

It's not on this website yet, but we're working on it. If you'd like to help write guides on subscriptions, please let us know.

For now, the specification includes details for how to write and execute subscriptions.

Does GraphQL replace Redux or other state management libraries?#

No, GraphQL isn’t a state management library - but it can reduce the need for one.

One benefit of state management libraries like Redux is that they can manipulate API responses into a format that your application understands. With GraphQL, you have control over what data you request and typically results are formatted in a client-friendly way by the graph design. So this benefit is already built-in. Many client libraries can also be used to manage state and have features like caching built-in. You may still decide to implement a state management library, but using it to format response data is generally not necessary.

What does the GraphQL Foundation do?#

The primary responsibility of the Foundation is to set policy and allocate the budget to maximize the sustainability of the GraphQL community. Members participate on a governing board that meets monthly and decides how to allocate its funding.

Where does the funding go when I become a member?#

The GraphQL Foundation is funded exclusively through the support of our members. The governing board sets an annual budget to use the dues to the maximum benefit of the community. Ways the Foundation distributes the money raised through memberships include:

• Providing grants and sponsorship to core community developers who are working in neutral roles.
• Funding core community IT infrastructure.
• Funding coordination, financial, and legal support programs for the Foundation and the GraphQL project ecosystem.
• Other community and developer support programs.

The GraphQL Foundation budget is realigned as the needs of the community change.

How are decisions made?#

As with other Linux Foundation projects, the governing board makes decisions through votes. Every vote is equal and no members have special voting rights or privileges. The charter currently limits the governing board to 25 members.

Who can join the GraphQL Foundation?#

GraphQL Foundation membership is open to companies who wish to support the GraphQL ecosystem. As the GraphQL Foundation is hosted at the Linux Foundation, members must also join the Linux Foundation.

Do I need to join the Foundation to participate in GraphQL development?#

No, Foundation membership is separate from the technical development community. There is no cost to participate in GraphQL development, although you must sign the free GraphQL Specification membership agreement in order to participate. These two things are different from each other.

Members join the Foundation in order to provide essential funding and participate in the decisions on how it is used. Developers join the GraphQL Specification in order to contribute ideas, code, and other content. Many companies do both.

How do I participate in technical development?#

We would love to have you! The best place to get started is the GraphQL Working Group, which meets monthly. Open a PR to add yourself to the agenda, and you are welcome to join.

Otherwise, you can get involved in any of our other projects.

Who founded the organization?#

The GraphQL Foundation was founded by Apollo, AWS, Butterfly Network, Dgraph Labs, Facebook, Gatsby, GraphZen, Hasura, IBM, Intuit, Neo4j, Novvum, Pipefy, Salsify, Solo.io and Thicit.

Who is currently a member?#

You can learn more about our membership on the GraphQL Foundation membership page.

How do we join?#

You can become a member of GraphQL Foundation and the Linux Foundation by completing our membership application form.