Skip to content

Commit

Permalink
Adding more FAQs answers based on feedback (graphql#1005)
Browse files Browse the repository at this point in the history
  • Loading branch information
Itsaadarsh committed Feb 23, 2021
1 parent 9a4c19d commit 4fd577e
Show file tree
Hide file tree
Showing 4 changed files with 51 additions and 3 deletions.
18 changes: 17 additions & 1 deletion src/content/faq/BestPractices.md
Original file line number Diff line number Diff line change
Expand Up @@ -57,4 +57,20 @@ 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 validations 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, The `data` field containing the result of the operation, The `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?

**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. 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.

**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. It requires less effort to use because, in contrast to the schema-first approach, it doesn’t depend on an excessive amount of tooling.
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.
24 changes: 23 additions & 1 deletion src/content/faq/GettingStarted.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,4 +47,26 @@ 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).

### 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 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, using a library like Apollo for implementing the GraphQL multipart request specification.

**Overkill for small applications** : While GraphQL is the right solution for multiple microservices, you’d better go for REST architecture in case of a simple app. REST can be also a valuable approach for connecting resource-driven apps that don’t need the flexible queries offered by GraphQL.

**GraphQL Query Complexity** : Don't mistake GraphQL as a replacement for server-side databases. It is just a simple 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 single time. So there must be a mechanism like maximum query depths, query complexity weighting, avoiding recursion, or persistent queries to stop inefficient requests from the client-side.

For more information on querying in GraphQL, check out our [documentation](/learn/queries/).
8 changes: 7 additions & 1 deletion src/content/faq/Specification.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,4 +21,10 @@ There are more ways to get involved with GraphQL beyond the specification though

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).
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.

0 comments on commit 4fd577e

Please sign in to comment.