Edit in GitHubLog an issue

GraphQL

GraphQL is a language for querying and manipulating data. It is widely viewed as more powerful, flexible, and efficient than REST.

Benefits provided by GraphQL#

Using GraphQL provides the following benefits:

Predictable results from your queries#

A GraphQL query returns only data the user asks for in their query.

Single request for many results#

A single request made through GraphQL can return any number of resources and their fields by following references between them as defined in the typed schema.

Organized data with a typed schema#

A single schema defines how users access data using GraphQL. These schemas, formatted as JSON objects, let users know exactly how to get the data they need.

The following is an example of a schema that defines a Species type with name and origin fields:

Copied to your clipboard
1type Species {
2 name: String
3 origin: Planet
4}
5type Planet {
6 name: String
7}

Why use GraphQL over REST#

While GraphQL and REST are both specifications for constructing and querying APIs, GraphQL has some significant advantages over REST.

No versioning#

REST APIs typically have multiple versions, such as v1, v2, etc. This is because updating endpoints in REST will often impact existing queries.

With GraphQL, there is no need for versioning, since new types and fields can be added to the schema without impacting existing queries.

Removing fields is done through deprecation instead of deleting them from the schema. If an old query tries to read a deprecated field, GraphQL displays a customized warning.

Copied to your clipboard
1type ExampleType {
2 firstName: String
3 lastName: String
4 name: String @deprecated(reason: "Split this field into two. Use `firstName` and `lastName`")
5}

This prevents old queries from throwing confusing errors when trying to read outdated fields, lending to code maintainability.

Faster and more efficient#

REST APIs typically require loading from multiple URLs. Imagine a REST API designed to get users and their forum posts. users/<id> would return information like name and user/<id>/posts would have to be queried separately to return the user's comments.

With GraphQL, these types and their fields are returned using one query, which saves calls to the API.

In the following schema example, a User type contains a posts field, which is an array of Post types:

Copied to your clipboard
1type Query {
2 user(id: Int): User
3 # This is our resolver; our entry into the query
4 # It lets us query `user` with an argument `id`
5 # And Expects to return a type `User`
6 # Yes, you can leave comments in schemas!
7}
8
9type User {
10 id: Int!
11 name: String
12 posts: [Post]
13}
14
15type Post {
16 id: Int!
17 title: String
18 author: User
19}

A query for this schema that requests the name and all the post titles for a specific user would look like the following:

Copied to your clipboard
1{
2 user(id: 12345) {
3 name
4 posts {
5 title
6 }
7 }
8}

The data response for the query would look like the following:

Copied to your clipboard
1{
2 "data": {
3 "user": {
4 "name": "Jane Doe"
5 "posts": [
6 {
7 title: "Hello World"
8 },
9 {
10 title: "I Love GraphQL"
11 }
12 ]
13 }
14 }
15}

Sample queries#

Simple query#

Imagine a database that simply contains an object User, with the fields name, email, and phone.

Copied to your clipboard
1type Query {
2 user: User
3}
4
5type User {
6 name: String
7 email: String
8 phone: String
9}

A simple query requesting this data would look like the following:

Copied to your clipboard
1{
2 user {
3 name
4 email
5 phone
6 }
7}

The response to this query would look like the following:

Copied to your clipboard
1{
2 "data": {
3 "user": {
4 "name": "Jane Doe"
5 "email": "JaneDoe@example.com"
6 "phone": "012-345-6789"
7 }
8 }
9}

Custom data query#

What if you don't need the phone number from User? The previous query can be rewritten to return specific fields:

Copied to your clipboard
1{
2 user {
3 name
4 email
5 }
6}

The response only provides the data requested:

Copied to your clipboard
1{
2 "data": {
3 "user": {
4 "name": "Jane Doe"
5 "email": "JaneDoe@example.com"
6 }
7 }
8}

Arguments in a query#

Now, what if you had multiple users and needed to grab a specific one using its id? Well, with GraphQL you can pass arguments into the query:

Copied to your clipboard
1{
2 user(id: 12345) {
3 id
4 name
5 email
6 }
7}

The response would look like the following:

Copied to your clipboard
1{
2 "data": {
3 "user": {
4 "id": "12345"
5 "name": "Jane Doe"
6 "email": "JaneDoe@example.com"
7 }
8 }
9}

Query connected resources#

In this example, imagine that in our database a User is associated with multiple hobbies. The schema would look like the following:

Copied to your clipboard
1type Query {
2 user: User
3}
4
5type User {
6 name: String
7 email: String
8 phone: String
9 hobbies: [Hobby]
10}
11
12type Hobby {
13 name: String
14 frequency: String
15}

The following query requests the hobbies associated with a specific user:

Copied to your clipboard
1{
2 user(id: 12345) {
3 name
4 email
5 phone
6 hobbies {
7 name
8 frequency
9 }
10 }
11}

The response would look like the following:

Copied to your clipboard
1{
2 "data": {
3 "user": {
4 "name": "Jane Doe"
5 "email": "JaneDoe@example.com"
6 "phone": "012-345-6789"
7 "hobbies": [
8 {
9 "name": "painting",
10 "frequency": "weekly"
11 },
12 {
13 "name": "video games",
14 "frequency": "daily"
15 }
16 ]
17 }
18 }
19}

Notice how the user's hobbies are returned in an array as defined in the schema.

Learn more#

This topic just covers the basics of GraphQL. To learn more, visit the GraphQL website.

  • Privacy
  • Terms of Use
  • Do not sell my personal information
  • AdChoices
Copyright © 2022 Adobe. All rights reserved.