Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Adding more FAQs answers based on feedback (#1005) #1009

Open
wants to merge 4 commits into
base: source
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 45 additions & 1 deletion src/content/faq/BestPractices.md
Original file line number Diff line number Diff line change
Expand Up @@ -57,4 +57,48 @@ You can read more about [how versioning works in GraphQL](/learn/best-practices/

One of the benefits of GraphQL is that it's inherently self-documenting. This means that when you use an interactive tool like [GraphiQL](https://github.com/graphql/graphiql), you’re able to explore what data is exposed by your GraphQL API. This includes the [fields](/learn/queries/#fields), [types](/learn/schema/#type-system), and more. You can also add a [description field](https://spec.graphql.org/draft/#sec-Documentation) 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.
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.

### Does GraphQL introduce a single point of failure?

One concern people have with this architecture is that the GraphQL gateway looks like a single point of failure. Everything depends on it, so if it goes down, then everything breaks. Except not exactly. The GraphQL gateway is completely stateless, meaning it doesn't store any data itself. It only communicates with external data sources. Once a request is finished processing, the GraphQL server forgets everything about it. Because of this stateless nature, the GraphQL gateway can actually live on several servers behind some load balancers. Now if one of the gateway instances goes down, the request can still be sent to one of the other instances.

### How can I do error handling?

GraphQL servers are able to handle errors by default, both for syntax and validation errors. You've probably already seen this when using GraphiQL or any other playground to explore GraphQL APIs. But often the default way is not sufficient for more complex situations or to sophistically handle the errors from a frontend application.

**GraphQL Error Object** : Error handling is described in the GraphQL specification and is part of the default structure of any GraphQL response. This response consists of 3 fields, a `data` field containing the result of the operation, an `errors` field containing all the errors that occurred during the execution of the operation, and an optional `extensions` field that contains meta data about the operation.

### Schema-first or code-first?
Itsaadarsh marked this conversation as resolved.
Show resolved Hide resolved

GraphQL schema is a set of rules describing the functionality available to the client, including specification of operations (queries and mutations) that can be executed to execute against your data source. If you ever decide to build a GraphQL service at some point you would need to chose which approach you want to go with. In either case, we will end up with a fully functional GraphQL service, but this choice will influence your project in terms of the amount of work you will need to put to achieve certain things like scaling your project etc.

**Schema-first** indicates that we first define the schema for the GraphQL service and then we implement the code by matching the definitions in the schema. To code the schema, we use the [Schema Definition Language (SDL)]('https://www.howtographql.com/basics/2-core-concepts/), a syntax created to represent the GraphQL data model. Because of this, this approach may also be called SDL-first.

**PROS**

It resembles doing test-driven development (TDD) because developers must consider the different use cases.

It follows the dependency inversion principle (DIP), which makes the solution more abstract and less tied to dependencies.

It reduces development time by allowing frontend and backend teams to work simultaneously.

**CONS**

Reusing SDL definitions may involve a lot of boilerplate and repeated code.

Ensuring that the schema definition is in sync with the resolvers at all times.

Composing a number of existing (and distributed) schemas into a single schema.

**Code-first**, indicates that we start by coding the resolvers, and then, from code as a single source of truth, we have the schema generated as an artifact. Thus, we still have a schema, but instead of being manually created, it is created through running a script. This approach may also be called resolver-first.

**PROS**

It can work as a single source of truth as it keeps stored both the schema definitions as well as resolvers.

It offers better manageability if you expect your schema to grow in complexity or size.

**CONS**

Having both the definitions and resolves might be less readable.
4 changes: 4 additions & 0 deletions src/content/faq/General.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,3 +56,7 @@ If this is confusing, don’t worry - there’s a lot going on. To get a more vi
The [GraphQL Foundation](https://foundation.graphql.org/faq/) 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](https://www.linuxfoundation.org/) and consists of [representatives from dozens of different companies](https://foundation.graphql.org/members/). 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](https://foundation.graphql.org/).

### Does GraphQL only work with graph-like structures or data sources that are graph-based?

No, the "graph" in GraphQL is only used to represent the graph-like structure of data. It's a misconception that you need to rewrite your database to adopt GraphQL. There is no limitation in the GraphQL ecosystem that enforces that the data source should be a graph. GraphQL can be a wrapper around any data source. GraphQL is a query language for your API which means it is a syntax of how to ask for data.
22 changes: 21 additions & 1 deletion src/content/faq/GettingStarted.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,4 +47,24 @@ Before you start your learning journey, make sure you know [what an API is](http

No, not at all. [GraphQL is a specification](https://spec.graphql.org/) that can be [implemented in any language](/learn/schema/#type-language). Our [Code page](/code/) 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](https://www.youtube.com/watch?v=9sc8Pyc51uU) and [GraphQL.js](/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.
It’s understandable why you’d think this, though. GraphQL was introduced at a [React conference](https://www.youtube.com/watch?v=9sc8Pyc51uU) and [GraphQL.js](/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.

### Can I use GraphQL to make graphs or charts?

Yes, graphql2chartjs is an open source tool that reshapes your GraphQL data as per the ChartJS API. This makes building charts as easy as simply making a GraphQL query. The idea behind this tool was to leverage GraphQL's realtime subscriptions to build realtime charts by restructuring the GraphQL data to a form that ChartJS expects and generate ChartJS compliant data object from your GraphQL response by simply adding a few aliases in your GraphQL query.

For more information on graphql2chartjs, check out their [documentation](https://github.com/hasura/graphql2chartjs).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This seems like a cool library. But I'm a little concerned that it was last updated in 2019 & has a few open issues suggesting that things aren't working. Do you have any experience with it?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Well, I haven't worked with this library yet. So do you want me to remove it?


### What are the downsides of GraphQL?

Although GraphQL has negligible downsides over its upsides, here are some downsides of GraphQL.

**GraphQL Caching** : It is complicated to implement a simplified cache with GraphQL than implementing it in REST. In a REST API, we access resources with URLs, so we can cache on a resource level. On the other hand, in GraphQL, it is very complex because each query can be different, even though it operates on the same entity. But most of the libraries built on top of GraphQL offer an efficient caching mechanism.

For more information on caching using GraphQL, check out our [documentation](/learn/caching/).

**File uploading** : Since GraphQL doesn’t understand files, a file uploading feature is not included in its specification. You won’t have to deal with this limitation in case of REST, as there you can POST or PUT whatever content you want to. To allow file uploads in your GraphQL web app, there are several options: using Base64 encoding, making a separate API endpoint just for this purpose, or using a library like [Apollo](https://github.com/apollographql/apollo-server) for implementing the GraphQL multipart request specification.

**GraphQL Query Complexity** : Don't mistake GraphQL as a replacement for server-side databases. It is just a query language. When we have to access multiple fields in one query whether it is in a RESTful architecture or GraphQL, the varied resources and fields still have to be retrieved from a data source, so it also shows the same problems when a client requests too many nested fields data at a time. Mechanisms like maximum query depths, query complexity weighting, avoiding recursion, or persisted queries help to stop inefficient requests from the client-side.

For more information on querying in GraphQL, check out our [documentation](/learn/queries/).
7 changes: 7 additions & 0 deletions src/content/faq/Specification.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,3 +30,10 @@ If your organization uses and benefits from GraphQL, please consider becoming a
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](https://github.com/graphql/graphql.github.io/issues/993).

For now, the specification includes details for [how to write and execute subscriptions](https://spec.graphql.org/draft/#sec-Subscription).

### What is the N+1 problem I keep hearing about?

The N + 1 problem occurs when an application gets data from the database, and then loops through the result of that data. That means we call to the database again and again and again. In total, the application will call the database once for every row returned by the first query (N) plus the original query ( + 1). The N+1 query problem is a common one to encounter with ORMs (Object Relational Mappers) and their capabilities around lazy loading.

Most GraphQL server frameworks support the idea of a [DataLoader](https://github.com/graphql/dataloader). Dataloader is a library that batches consecutive requests and makes a single data request under the hood. This request can be made to any data source, like a database or a web service. A Dataloader takes in an array as argument, processes data using that argument and returns an array of objects. The element at the nth index of the returned array will be considered by the dataloader as the data for the nth element in the input argument.