What does it solve ?

GraphQL is a query language for your API, and a server-side runtime for executing queries by using a type system you define for your data.

At its core, GraphQL enables declarative data fetching where a client can specify exactly what data it needs from an API.

Instead of multiple endpoints that return fixed data structures, a GraphQL server only exposes a single endpoint and responds with precisely the data a client asked for.

A GraphQL service is created by defining types and fields on those types, then providing functions for each field on each type.

GraphQL - A Query Language for APIs

Example

Let's define simple, related data structure

(NF3)

Rest API

HTTP GET /books/:id

HTTP GET /books/:id/authors/

HTTP GET /books/:id/movies/

HTTP GET /books/:id/stars/

    

{
  "data": {
    "book": {
      "name": "Book2",
      "genre": "222",
      "more": "not relevant fields",
      "author": {
        "age": 44,
        "name": "Mike",
        "id": "5e5629fc4e98b96691966c76",
        "more": "not relevant fields"
      },
      "stars": {
        "stars": 5,
        "id": "3",
        "bookId": "5e562a384e98b96691966c77",
        "more": "not relevant fields"
      },
      "movie": {
        "title": "Episode I",
        "year": 2008,
        "id": "58559",
        "more": "not relevant fields"
      }
    }
  }
}

The problem

• Overfetching - Download unnecessary data
 
• Underfetching - An endpoint doesn't return enough of the right information, needs to send multiple requests (n+1)

GraphQL

With GraphQL we can retrieve all related data with one single query using only one exposed api

GraphQL

  {
    book(id: "2"){
      name
      genre
      author{
        age,
        name
        id
      }
      stars{
        stars
        id
        bookId
      }
      movie{
        title
        year
        id
      }
    }
  }

{
  "data": {
    "book": {
      "name": "Book2",
      "genre": "222",
      "author": {
        "age": 44,
        "name": "Mike",
        "id": "5e5629fc4e98b96691966c76"
      },
      "stars": {
        "stars": 5,
        "id": "3",
        "bookId": "5e562a384e98b96691966c77"
      },
      "movie": {
        "title": "Episode I",
        "year": 2008,
        "id": "58559"
      }
    }
  }
}

With dynamic fields selection, we just can solve the problem of over and under fetching

GraphQL - Accessing the fields

  {
    book(id: "2"){
      name
      author{
      age 
      }
      stars{
        stars
      }
      movie{
        title
      }
    }
  }

  {
    "data": {
      "book": {
        "name": "Book2",
        "author": {
          "age": 44
        },
        "stars": {
          "stars": 5
        },
        "movie": {
          "title": "Episode I"
        }
      }
    }
  }

GraphQL - Accessing the fields

  {
    book(id: "2"){
      name
      genre
      author{
      age 
      name
      }
      stars{
        stars
      }
      movie{
        title
      }
    }
  }

{
"data": {
  "book": {
    "name": "Book2",
    "genre": "222",
    "author": {
      "name": "Mike",
      "age": 44,
    },
    "stars": {
      "stars": 5,
    },
    "movie": {
      "title": "Episode I",
    }
  }
}
}

What if ?

Can we still have

the relations ?

Can we still retrieve the data with one single

query ?

Yes, we can !

GraphQL has a clear separation of structure and behavior. The structure of a GraphQL server is — as we just discussed — its schema, an abstract description of the server’s capabilities.

This structure comes to life with a concrete implementation that determines the server’s behavior. Key components for the implementation are so-called resolver functions.

Each field in a GraphQL schema is backed by a resolver.

Definding the type with JS

    const graphql = require('graphql')
    const { GraphQLObjectType, GraphQLID, 
            GraphQLList,GraphQLString,GraphQLInt } = graphql

    const AuthorType = new GraphQLObjectType({
      name: "Author",
      fields: () => ({
        id: { type: GraphQLID },
        name: { type: GraphQLString },
        age: { type: GraphQLInt },
        books: {
          type: new GraphQLList(BookType),
          resolve: (parent, args) => {
            return Book.find({ authorId: parent.id }) // mongo db
          }
        }
      })
    })

Fetching Data with Queries

  {
    books {
      name
      genre
      id
      author{     
        name
        age
        id
      }
    }
  }
  
  

    {
      "data": {
        "books": [

          {
            "name": "Book1",
            "genre": "1111",
            "id": "5e56294a4e98b96691966c74",    
            "author": {
              "name": "Alex",
              "age": 39,
              "id": "5e56255c62c9836008df46d7"      
            }
          },
          
          ....
        ]
      }
    }
              

Queries with Arguments

  {
    book(id: "5e562...") {   
      name
      genre
      id
      author{     
        name
        age
        id
      }
    }
  }
  
  

    {
      "data": {
            "name": "Book1",
            "genre": "1111",
            "id": "5e56294a4e98b96691966c74",    
            "author": {
              "name": "Alex",
              "age": 39,
              "id": "5e56255c62c9836008df46d7"      
      }
    }
              

So we need some way of making changes to the data that’s currently stored in the backend.

With GraphQL, these changes are made using mutations.

There generally are three kinds of mutations

• creating new data
• updating existing data
• deleting existing data

Writing Data with Mutations

  mutation {

  createBook(name: "Book 10", genre: "Sci-Fi") {    
    name
    id
  }

  updateBook(name: "Book 10", genre: "Sci-Fi") {    
    name
    id
  }

  deleteBook(id: ...) {    
    name
    id
  }
}
  
  

    {
      "data": {
        "name": "Book 10",
        "id": "5e56294a4e98b96691966c74"    
    }
              

Realtime Updates with Subscriptions

Another important requirement for many applications today is to have a realtime connection to the server in order to get immediately informed about important events. For this use case, GraphQL offers the concept of subscriptions.

When a client subscribes to an event, it will initiate and hold a steady connection to the server. Whenever that particular event then actually happens, the server pushes 🤓 the corresponding data to the client.

Unlike queries and mutations that follow a typical “request-response-cycle”, subscriptions represent a stream of data sent over to the client.

😎

              subscription {
                newBook {
                  name
                  genre
                }
              }
            

After a client sent this subscription to a server, a connection is opened between them. Then, whenever a new mutation is performed that creates a new Book, the server sends the information about this book over to the client

              {
                "newBook": {
                  "name": "Book 22",
                  "genre": "Sci-Fi"
                }
              }
            

Use Cases

Any Type of Technology

Any Type of DB

Any Structure

Any Location