From 191bd1e6f673e8521e85df7fb2e59a47f6eba179 Mon Sep 17 00:00:00 2001 From: carolstran Date: Mon, 2 Nov 2020 16:10:08 +0100 Subject: [PATCH 1/3] Initial commit of FAQ page --- src/assets/css/_css/docs.less | 5 ++++ src/components/FAQLayout/index.tsx | 37 ++++++++++++++++++++++++++++ src/components/HeaderLinks/index.tsx | 1 + src/content/faq/General.md | 27 ++++++++++++++++++++ src/templates/doc.tsx | 6 ++++- 5 files changed, 75 insertions(+), 1 deletion(-) create mode 100644 src/components/FAQLayout/index.tsx create mode 100644 src/content/faq/General.md diff --git a/src/assets/css/_css/docs.less b/src/assets/css/_css/docs.less index 0ad08aa862..963887fab2 100644 --- a/src/assets/css/_css/docs.less +++ b/src/assets/css/_css/docs.less @@ -162,6 +162,11 @@ } } + .faq-questions::before { + content: "\A"; + white-space: pre; + } + img { max-width: 100%; } diff --git a/src/components/FAQLayout/index.tsx b/src/components/FAQLayout/index.tsx new file mode 100644 index 0000000000..e84d0b2af4 --- /dev/null +++ b/src/components/FAQLayout/index.tsx @@ -0,0 +1,37 @@ +import React from "react" +import { Link } from "gatsby" +import Marked from '../Marked' +import { toSlug } from '../../utils/slug' + +interface Props { + title: string + questions: string + rawMarkdownBody: string +} + +const index = ({ title, questions, rawMarkdownBody }: Props) => { + return ( +
+
+
+

{title}

+ {questions && ( +
+ {questions + .split(',') + .map(question => ( + + {question} + + )) + } +
+ )} + {rawMarkdownBody} +
+
+
+ ) +} + +export default index diff --git a/src/components/HeaderLinks/index.tsx b/src/components/HeaderLinks/index.tsx index d939ce6a95..720da9f49f 100644 --- a/src/components/HeaderLinks/index.tsx +++ b/src/components/HeaderLinks/index.tsx @@ -11,6 +11,7 @@ const links: LinkItem[] = [ { section: "learn", text: "Learn", href: "/learn/" }, { section: "code", text: "Code", href: "/code/" }, { section: "community", text: "Community", href: "/community/" }, + { section: "faq", text: "FAQ", href: "/faq/" }, { section: "spec", text: "Spec", diff --git a/src/content/faq/General.md b/src/content/faq/General.md new file mode 100644 index 0000000000..875455e24f --- /dev/null +++ b/src/content/faq/General.md @@ -0,0 +1,27 @@ +--- +title: Frequently Asked Questions (FAQ) +layout: faq +category: General +permalink: /faq/ +questions: Why should I use GraphQL?,Is GraphQL a database language like SQL?,Does GraphQL replace REST?,How can I learn GraphQL?,Is GraphQL frontend or backend?,Does GraphQL replace Redux or other state management libraries?,Is GraphQL only for React or JavaScript developers?,What is a GraphQL client and why would I use one?,What is the GraphQL Foundation?,How can I contribute to the GraphQL specification? +--- + +## Why should I use GraphQL? + +## Is GraphQL a database language like SQL? + +## Does GraphQL replace REST? + +## How can I learn GraphQL? + +## Is GraphQL frontend or backend? + +## Does GraphQL replace Redux or other state management libraries? + +## Is GraphQL only for React or JavaScript developers? + +## What is a GraphQL client and why would I use one? + +## What is the GraphQL Foundation? + +## How can I contribute to the GraphQL specification? \ No newline at end of file diff --git a/src/templates/doc.tsx b/src/templates/doc.tsx index c22a9de1d6..e877216ccc 100644 --- a/src/templates/doc.tsx +++ b/src/templates/doc.tsx @@ -4,6 +4,7 @@ import Layout from "../components/Layout" import DocsLayout from "../components/DocsLayout" import BlogLayout from '../components/BlogLayout'; import CodeLayout from "../components/CodeLayout"; +import FAQLayout from "../components/FAQLayout"; interface Props { data: any @@ -14,12 +15,13 @@ const layoutMap: any = { docs: DocsLayout, blog: BlogLayout, code: CodeLayout, + faq: FAQLayout, } const Blog = ({ data, pageContext }: Props) => { const { doc: { - frontmatter: { title, date, permalink, byline, guestBio, layout }, + frontmatter: { title, date, permalink, byline, guestBio, layout, questions }, rawMarkdownBody, }, nextDoc, @@ -33,6 +35,7 @@ const Blog = ({ data, pageContext }: Props) => { permalink={permalink} byline={byline} guestBio={guestBio} + questions={questions} rawMarkdownBody={rawMarkdownBody} nextDoc={nextDoc} sideBarData={pageContext.sideBarData} @@ -52,6 +55,7 @@ export const query = graphql` guestBio sublinks layout + questions } id rawMarkdownBody From 036ef54e68599faa1a63537f1bdf72737e20e954 Mon Sep 17 00:00:00 2001 From: carolstran Date: Tue, 3 Nov 2020 00:38:57 +0100 Subject: [PATCH 2/3] Initial commit - 8/11 answers complete --- src/content/faq/General.md | 58 +++++++++++++++++++++++++++++++++++++- 1 file changed, 57 insertions(+), 1 deletion(-) diff --git a/src/content/faq/General.md b/src/content/faq/General.md index 875455e24f..f790453709 100644 --- a/src/content/faq/General.md +++ b/src/content/faq/General.md @@ -24,4 +24,60 @@ questions: Why should I use GraphQL?,Is GraphQL a database language like SQL?,Do ## What is the GraphQL Foundation? -## How can I contribute to the GraphQL specification? \ No newline at end of file +## How can I contribute to the GraphQL specification? + +## Does GraphQL use HTTP? + + + +## Who is behind GraphQL? + +Loads of people! The [GraphQL specification and all related projects](http://github.com/graphql/) are open source, so anyone is welcome to [contribute](#how-can-i-contribute-to-the-specification). That being said, there is a structure in place behind the repositories - particularly for resolving conflicts within the community and guiding technical decisions. + +The [GraphQL Foundation](#what-is-the-graphql-foundation) provides most of the oversight for GraphQL and is made up of [representatives from 20 different companies](https://foundation.graphql.org/members/). There are also monthly virtual [GraphQL Working Group (WG)](https://github.com/graphql/graphql-wg) meetings. These meetings are operated by the GraphQL Foundation and designed to bring together maintainers of commonly used GraphQL libraries and tools, as well as significant contributors to the GraphQL community. While it tends to be mostly foundation members in attendance, the WG meetings are completely open. Anyone is able to join and [propose items to the agenda](https://github.com/graphql/graphql-wg/blob/master/agendas/). Additionally, GraphQL will soon have a Technical Steering Committee (TSC) to advise on implementation details. 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](https://landscape.graphql.org/). + +## How does GraphQL affect my product’s performance? + + + +## Does GraphQL support offline usage? + +No, or at least not natively. But there are [GraphQL clients](#what-is-a-graphql-client-and-why-would-i-need-one) that enable you to build offline-first through caching, holding your mutations in a queue, service workers, or another feature designed to perform data operations while offline. + +You can find a [list of GraphQL clients on our Code page](/code/#graphql-clients). + +## How does authentication work with GraphQL? + +There’s nothing special about it within the specification, but you can implement authentication with common patterns, such as [OAuth](https://oauth.net/). Some [GraphQL libraries](/code/) include a specific protocol for authentication as well. Although if you’re working with a pipeline model, we recommend that [GraphQL should be placed after all authentication middleware](/learn/serving-over-http/#web-request-pipeline). + +If you’re using [GraphQL.js](/graphql-js/) to build your API server, we have documentation on [handling authentication with Express middleware](/graphql-js/authentication-and-express-middleware/). + +## How can I set up authorization with GraphQL? + +As tempting as it is to define your authorization logic in your GraphQL implementation, we recommend enforcing authorization behavior in the [business logic layer](/learn/thinking-in-graphs/#business-logic-layer). That way, you have a single source of truth for authorization. + +For a more detailed explanation, go to our [Authorization documentation](/learn/authorization/). + +## What are the security concerns with GraphQL? + + + +## How can I document my GraphQL API? + +One of the benefits of GraphQL is that it is 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. For many, this provides sufficient API reference documentation. But it doesn’t reduce the need for other forms of documentation, such as guides that explain how the general concepts tie into your specific use case. + +## What’s the best way to follow specification releases? + +The latest working draft release of the GraphQL specification can be found at [spec.graphql.org/draft](https://spec.graphql.org/draft/). Previous editions can also be found at permalinks that match their [release tag](https://github.com/graphql/graphql-spec/releases). + +## Does GraphQL replace ORMs? + +No, GraphQL is a specification. It [doesn’t understand the concept of databases](#is-graphql-a-database-language-like-sql). There are, however, ORMs built specifically for GraphQL. A few of those are listed under the [Services section of our Code page](/code/#services). + +## Is GraphQL the right fit for designing a microservice architecture? + +Yes, there are many benefits to using GraphQL within a microservice architecture. Some of these benefits include [caching](/learn/caching/), request budgeting, and planning out query schedules. + +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 of your data to the frontend from a single API. \ No newline at end of file From 2d6b666cde7dc10420db6f3619082f7eb1fd900b Mon Sep 17 00:00:00 2001 From: carolstran Date: Tue, 3 Nov 2020 01:18:47 +0100 Subject: [PATCH 3/3] Update answers based on initial feedback from Ivan --- src/content/faq/General.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/src/content/faq/General.md b/src/content/faq/General.md index f790453709..1b86bfb027 100644 --- a/src/content/faq/General.md +++ b/src/content/faq/General.md @@ -50,7 +50,7 @@ You can find a [list of GraphQL clients on our Code page](/code/#graphql-clients ## How does authentication work with GraphQL? -There’s nothing special about it within the specification, but you can implement authentication with common patterns, such as [OAuth](https://oauth.net/). Some [GraphQL libraries](/code/) include a specific protocol for authentication as well. Although if you’re working with a pipeline model, we recommend that [GraphQL should be placed after all authentication middleware](/learn/serving-over-http/#web-request-pipeline). +There’s nothing special about it within the specification, but you can implement authentication with common patterns, such as [OAuth](https://oauth.net/) or [JWT](https://jwt.io/). Some [GraphQL libraries](/code/) include a specific protocol for authentication as well. Although if you’re working with a pipeline model, we recommend that [GraphQL should be placed after all authentication middleware](/learn/serving-over-http/#web-request-pipeline). If you’re using [GraphQL.js](/graphql-js/) to build your API server, we have documentation on [handling authentication with Express middleware](/graphql-js/authentication-and-express-middleware/). @@ -66,7 +66,9 @@ For a more detailed explanation, go to our [Authorization documentation](/learn/ ## How can I document my GraphQL API? -One of the benefits of GraphQL is that it is 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. For many, this provides sufficient API reference documentation. But it doesn’t reduce the need for other forms of documentation, such as guides that explain how the general concepts tie into your specific use case. +One of the benefits of GraphQL is that it is 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. + +For many, this provides sufficient API reference documentation. But it doesn’t reduce the need for other forms of documentation, such as guides that explain how the general concepts tie into your specific use case. ## What’s the best way to follow specification releases? @@ -78,6 +80,6 @@ No, GraphQL is a specification. It [doesn’t understand the concept of database ## Is GraphQL the right fit for designing a microservice architecture? -Yes, there are many benefits to using GraphQL within a microservice architecture. Some of these benefits include [caching](/learn/caching/), request budgeting, and planning out query schedules. +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 of your data to the frontend from a single API. -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 of your data to the frontend from a single API. \ No newline at end of file +There are many ways to create an API gateway, but the benefit of using GraphQL is that you can take advantage of features like [caching](/learn/caching/), request budgeting, and planning out query schedules. \ No newline at end of file