From e02ac49cc65e149a5a782bc26ad3fa6839a11843 Mon Sep 17 00:00:00 2001
From: Mandi Wise <hello@mandiwise.com>
Date: Sun, 20 Oct 2024 15:05:46 -0600
Subject: [PATCH 1/5] Update Learn introduction page.
---
src/globals.css | 8 ++++
src/pages/learn/index.mdx | 84 ++++++++++++++++++++++++++++++---------
2 files changed, 74 insertions(+), 18 deletions(-)
diff --git a/src/globals.css b/src/globals.css
index 1e02497aef..4fa8798e69 100644
--- a/src/globals.css
+++ b/src/globals.css
@@ -486,3 +486,11 @@ div[id^="headlessui-menu-items"] {
font-size: 13px;
padding: 7px 14px;
}
+
+.learn-subtitle {
+ @apply mt-2;
+ @apply pb-2;
+ @apply border-neutral-200;
+ @apply border-b;
+ @apply text-xl;
+}
diff --git a/src/pages/learn/index.mdx b/src/pages/learn/index.mdx
index 09561fa653..8fb6acc4fa 100644
--- a/src/pages/learn/index.mdx
+++ b/src/pages/learn/index.mdx
@@ -1,15 +1,14 @@
+import { Callout } from "nextra/components"
+
# Introduction to GraphQL
-> Learn about GraphQL, how it works, and how to use it. Looking for documentation on how to build a GraphQL service?
-> There are libraries to help you implement GraphQL in [many different languages](/code). For an in-depth learning experience
-> with practical tutorials, see [the available training courses](/community/resources/training-courses).
+<p className="learn-subtitle">Learn about GraphQL, how it works, and how to use it</p>
+
+GraphQL is a query language for your API, and a server-side runtime for executing queries using a type system you define for your data. The [GraphQL specification](https://spec.graphql.org/) was open-sourced in 2015 and has since been implemented in a variety of programming languages. GraphQL also isn't tied to any specific database or storage engine and is instead backed by your existing code and data.
-GraphQL is a query language for your API, and a server-side runtime for executing queries using a type system you define for your
-data. GraphQL isn't tied to any specific database or storage engine and is instead backed by your existing code and data.
+## Describe your API with a type system
-A GraphQL service is created by defining types and fields on those types, then providing functions for each field on each type.
-For example, a GraphQL service that tells you who the logged in user is (`me`) as well as that user's name might look
-like this:
+A GraphQL service is created by [defining types and their fields](/learn/schema/), and then writing functions that [provide data for each field](/learn/execution/). For example, a GraphQL service that tells you the name of a logged-in user might look like this:
```graphql
type Query {
@@ -17,7 +16,6 @@ type Query {
}
type User {
- id: ID
name: String
}
```
@@ -25,18 +23,24 @@ type User {
Along with functions for each field on each type:
```js
-function Query_me(request) {
- return request.auth.user
+Query: {
+ me(obj, args, context, info) {
+ return context.request.auth.user
+ }
}
-function User_name(user) {
- return user.getName()
+User: {
+ name(obj, args, context, info) {
+ return context.db.getUserFullName(obj.id)
+ }
}
```
-After a GraphQL service is running (typically at a URL on a web service), it can receive GraphQL queries to validate and execute.
-The service first checks a query to ensure it only refers to the types and fields defined, and then runs the provided functions
-to produce a result.
+In the example above, the function that provides data for the `me` field on the `Query` type uses information about the authenticated user who made the request, while the the `name` field on the `User` type is populated by using that user's ID to fetch their full name from an existing database.
+
+## Query exactly what you need
+
+After a GraphQL service is running (typically at a URL on a web service), it can receive [GraphQL queries](/learn/queries/) to validate and execute from clients. The service first checks a query to ensure it only refers to the types and fields defined for the API and then runs the provided functions to produce a result.
For example, the query:
@@ -52,8 +56,52 @@ Could produce the following JSON result:
```json
{
- "me": {
- "name": "Luke Skywalker"
+ "data": {
+ "me": {
+ "name": "Luke Skywalker"
+ }
}
}
```
+
+With even a simple query, we can see some of the key features that make GraphQL so powerful. The client can make queries to the API that mirror the structure of the data that they need and then receive just that data in the expected shape with a single request—and without having to worry about what underlying data sources provided it.
+
+## Evolve your API without versioning
+
+Client requirements change over time and GraphQL allows your API to evolve in response to those needs and without the overhead of managing different API versions. For example, if a new feature calls for more specific name values to be available, then the `User` type could be updated as follows:
+
+```graphql
+type User {
+ fullName: String
+ nickname: String
+ name: String @deprecated(reason: "Use `fullName`.")
+}
+```
+
+GraphQL will continue to provide data as expected for the deprecated `name` field until it's determined that clients have updated their existing queries and the older field can be safely removed.
+
+## Try it out!
+
+The best way to learn GraphQL is to start writing queries. The query editors used throughout this guide are **interactive**, so try adding an `id` and `appearsIn` fields to the `hero` object to see an updated result:
+
+```graphql
+# { "graphiql": true }
+{
+ hero {
+ name
+ # add additional fields here!
+ }
+}
+```
+
+<Callout type="info">
+The examples in this guide are based on [a modified version of the SWAPI GraphQL schema](https://github.com/graphql/graphql.github.io/blob/source/src/components/marked/swapi-schema.tsx). Because these queries are designed for illustrative purposes, they will not run on the full version of the SWAPI GraphQL API due to differences between the two schemas. [You can try the full version of the API here.](https://graphql.org/swapi-graphql/)
+</Callout>
+
+## Next steps
+
+Now that you know some key GraphQL concepts, you're ready to learn about all of the different aspects of its [type system](/schema/).
+
+If you're already familiar with GraphQL and would like to read documentation on how to build a GraphQL service, then there are libraries to help you implement GraphQL in [many different languages](/community/tools-and-libraries/?tags=server). There are also many libraries available that allow [client applications to query existing GraphQL APIs](/community/tools-and-libraries/?tags=client).
+
+For an in-depth learning experience with practical tutorials, see [the available training courses](/community/resources/training-courses).
From b36cd7d49e78ed933be8dbc7b7f7fc1898966a07 Mon Sep 17 00:00:00 2001
From: Mandi Wise <hello@mandiwise.com>
Date: Tue, 22 Oct 2024 10:33:55 -0600
Subject: [PATCH 2/5] Apply suggestions from code review.
Co-authored-by: Benjie <benjie@jemjie.com>
---
src/pages/learn/index.mdx | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/src/pages/learn/index.mdx b/src/pages/learn/index.mdx
index 8fb6acc4fa..3b3d2a6288 100644
--- a/src/pages/learn/index.mdx
+++ b/src/pages/learn/index.mdx
@@ -4,11 +4,11 @@ import { Callout } from "nextra/components"
<p className="learn-subtitle">Learn about GraphQL, how it works, and how to use it</p>
-GraphQL is a query language for your API, and a server-side runtime for executing queries using a type system you define for your data. The [GraphQL specification](https://spec.graphql.org/) was open-sourced in 2015 and has since been implemented in a variety of programming languages. GraphQL also isn't tied to any specific database or storage engine and is instead backed by your existing code and data.
+GraphQL is a query language for your API, and a server-side runtime for executing queries using a type system you define for your data. The [GraphQL specification](https://spec.graphql.org/) was open-sourced in 2015 and has since been implemented in a variety of programming languages. GraphQL isn't tied to any specific database or storage engine—it is backed by your existing code and data.
## Describe your API with a type system
-A GraphQL service is created by [defining types and their fields](/learn/schema/), and then writing functions that [provide data for each field](/learn/execution/). For example, a GraphQL service that tells you the name of a logged-in user might look like this:
+A GraphQL service is created by [defining types and their fields](/learn/schema/), and then writing a function for each field to [provide the required data](/learn/execution/). For example, a GraphQL service that tells you the name of a logged-in user might look like this:
```graphql
type Query {
@@ -78,7 +78,7 @@ type User {
}
```
-GraphQL will continue to provide data as expected for the deprecated `name` field until it's determined that clients have updated their existing queries and the older field can be safely removed.
+Client tooling will encourage developers to use the new fields and remove usage of the deprecated `name` field. The field can be removed once it is determined it is no longer used; in the meantime GraphQL will continue to provide its data as expected.
## Try it out!
From 5e498fb6b6dd438a9c494b7ffd0e088b0bf4388c Mon Sep 17 00:00:00 2001
From: Mandi Wise <hello@mandiwise.com>
Date: Thu, 24 Oct 2024 10:34:32 -0600
Subject: [PATCH 3/5] Move libraries links and change resolver format.
---
src/pages/learn/index.mdx | 18 ++++++++----------
1 file changed, 8 insertions(+), 10 deletions(-)
diff --git a/src/pages/learn/index.mdx b/src/pages/learn/index.mdx
index 3b3d2a6288..ec3db24320 100644
--- a/src/pages/learn/index.mdx
+++ b/src/pages/learn/index.mdx
@@ -6,6 +6,8 @@ import { Callout } from "nextra/components"
GraphQL is a query language for your API, and a server-side runtime for executing queries using a type system you define for your data. The [GraphQL specification](https://spec.graphql.org/) was open-sourced in 2015 and has since been implemented in a variety of programming languages. GraphQL isn't tied to any specific database or storage engine—it is backed by your existing code and data.
+<Callout type="info">If you're already familiar with GraphQL and would like to read documentation on how to build a GraphQL service, then there are libraries to help you implement GraphQL in [many different languages](/community/tools-and-libraries/?tags=server). There are also many libraries available that allow [client applications to query existing GraphQL APIs](/community/tools-and-libraries/?tags=client).</Callout>
+
## Describe your API with a type system
A GraphQL service is created by [defining types and their fields](/learn/schema/), and then writing a function for each field to [provide the required data](/learn/execution/). For example, a GraphQL service that tells you the name of a logged-in user might look like this:
@@ -23,16 +25,14 @@ type User {
Along with functions for each field on each type:
```js
-Query: {
- me(obj, args, context, info) {
- return context.request.auth.user
- }
+// Provide data for the `me` field on the `Query` type
+function Query_me(obj, args, context, info) {
+ return context.request.auth.user
}
-User: {
- name(obj, args, context, info) {
- return context.db.getUserFullName(obj.id)
- }
+// Provide data for the `name` field on the `User` type
+function User_name(obj, args, context, info) {
+ return context.db.getUserFullName(obj.id)
}
```
@@ -102,6 +102,4 @@ The examples in this guide are based on [a modified version of the SWAPI GraphQL
Now that you know some key GraphQL concepts, you're ready to learn about all of the different aspects of its [type system](/schema/).
-If you're already familiar with GraphQL and would like to read documentation on how to build a GraphQL service, then there are libraries to help you implement GraphQL in [many different languages](/community/tools-and-libraries/?tags=server). There are also many libraries available that allow [client applications to query existing GraphQL APIs](/community/tools-and-libraries/?tags=client).
-
For an in-depth learning experience with practical tutorials, see [the available training courses](/community/resources/training-courses).
From 021d70e8f3391558aa911dc52b28c2ebeaf44c00 Mon Sep 17 00:00:00 2001
From: Benjie <benjie@jemjie.com>
Date: Thu, 24 Oct 2024 18:45:13 +0100
Subject: [PATCH 4/5] Apply suggestions from code review
---
src/pages/learn/index.mdx | 10 +++++-----
1 file changed, 5 insertions(+), 5 deletions(-)
diff --git a/src/pages/learn/index.mdx b/src/pages/learn/index.mdx
index ec3db24320..ec4a3503be 100644
--- a/src/pages/learn/index.mdx
+++ b/src/pages/learn/index.mdx
@@ -26,17 +26,17 @@ Along with functions for each field on each type:
```js
// Provide data for the `me` field on the `Query` type
-function Query_me(obj, args, context, info) {
+function Query_me(query, args, context, info) {
return context.request.auth.user
}
// Provide data for the `name` field on the `User` type
-function User_name(obj, args, context, info) {
- return context.db.getUserFullName(obj.id)
+function User_name(user, args, context, info) {
+ return context.db.getUserFullName(user.id)
}
```
-In the example above, the function that provides data for the `me` field on the `Query` type uses information about the authenticated user who made the request, while the the `name` field on the `User` type is populated by using that user's ID to fetch their full name from an existing database.
+In the example above, the function that provides data for the `me` field on the `Query` type uses information about the authenticated user who made the request, while the the `name` field on the `User` type is populated by using that user's ID to fetch their full name from a database.
## Query exactly what you need
@@ -64,7 +64,7 @@ Could produce the following JSON result:
}
```
-With even a simple query, we can see some of the key features that make GraphQL so powerful. The client can make queries to the API that mirror the structure of the data that they need and then receive just that data in the expected shape with a single request—and without having to worry about what underlying data sources provided it.
+With even a simple query, we can see some of the key features that make GraphQL so powerful. The client can make queries to the API that mirror the structure of the data that they need and then receive just that data in the expected shape with a single request—and without having to worry about which underlying data sources provided it.
## Evolve your API without versioning
From 0baca8742e9e11b56f227b986d88cf3dc2fdd59b Mon Sep 17 00:00:00 2001
From: Mandi Wise <hello@mandiwise.com>
Date: Tue, 29 Oct 2024 14:52:01 -0600
Subject: [PATCH 5/5] Fix subtitle border color in dark mode.
---
src/globals.css | 1 +
1 file changed, 1 insertion(+)
diff --git a/src/globals.css b/src/globals.css
index 4fa8798e69..7283537b57 100644
--- a/src/globals.css
+++ b/src/globals.css
@@ -493,4 +493,5 @@ div[id^="headlessui-menu-items"] {
@apply border-neutral-200;
@apply border-b;
@apply text-xl;
+ @apply dark:border-neutral-700/80;
}