GraphQL

The big picture

What is GraphQL?

A spec that describes a declarative query language that your
clients can use to ask an API for the exact data they want. This
is achieved by creating a strongly typed Schema for your API,
ultimate flexibility in how your API can resolve data, and client
queries validated against your Schema.

It’s just a spec. There are several implementations and variations

Server Side

  • Type Definitions
  • Resolvers
  • Query Definitions
  • Mutation Definitions
  • Subscription Definitions
  • Composition
  • Schema
  • Queries
  • Mutations
  • Subscription
  • Fragments

Client Side

Where does GraphQL fit in?

A GraphQL server with a connected DB

A GraphQL server as a layer in front of many 3rd party services and connects them all with one GraphQL API.

A hybrid approach where a GraphQL server has a connected DB and also communicates with 3rd party services

Node GraphQL Tools

  • Apollo server
  • GraphQL Yoga
  • Others

Servers

Tools

  • Prisma
  • many others
  • Amplify
  • Others

Services

Schemas

Creating a Schema

  • Using Schema Definition Language (Schema first)
  • Programmatically Creating a Schema using language constructs (code first)

Use the SDL to create your Schemas

  • Types - a construct defining a shape with fields
  • Fields - keys on a Type that have a name and a value type
  • Scalars - primitive value type built into GraphQL
  • Query - type that defines how clients can access data
  • Mutation- type that defines how clients can modify or create data
  • Subscription - type that used to push data to client from server (pub/sub)

Basic Types

  • Int - integer numbers (32bit only) for bigger number use custom scalers
  • Float
  • Boolean 
  • String
  • ID - just a string with special meaning

Bult-in Types

Query Type

What is a Query?

A Type on a Schema that defines operations clients can perform to access data that resembles the shape of the other Types in the Schema.

  • Create Query Type in the Schema using SDL
  • Add fields to the Query Type
  • Create Resolvers that for the fields

How?

Resolvers?

 

Functions that are responsible for returning values for fields that exist on Types in a Schema. Resolvers execution is dependent on the incoming client Query.

Creating Resolvers

  • Resolver names must match the exact field name on your Schema’s Types
  • Resolvers must return the value type declared for the matching field
  • Resolvers can be async
  • Can retrieve data from any source

Schema + Resolvers ⇒ Server

To create a server, at minimum, we need a Query Type with a field, and a Resolver for that field.

Arguments and Input Types

Arguments

  • Allows clients to pass variables along with Queries that can be used in your Resolvers to get data
  • Must be defined in your Schema
  • Can be added to any field
  • Either have to be Scalars or Input Types
  • Just like Types, but used for Arguments
  • All field value types must be other Input Types or Scalars

Input Type

Arguments in Resolvers

  • Arguments will be passed to field Resolvers as the second argument
  • The argument object will strictly follow the argument names and field types
  • Do whatever you want with them

Mutation Type

What are Mutations?

A Type on a Schema that defines operations clients can
perform to mutate data (create, update, delete). 

  •  Define Mutation Type on Schema using SDL
  • Add fields for Mutation type
  • Add arguments for Mutation fields
  • Create Resolvers for Mutation fields

Creating Mutations

Return values for Mutation fields

  • Dependent on your clients and use case
  • If using a client side GraphQL cache, you should return the exact values Queries return

Advanced SDL

Enums

A set of discrete values that can be used in place of Scalars. An enum field must resolve to one of the values in the Enum. Great for limiting a field to only a few different options.

Abstract Types that can’t be used as field values but instead used as foundations for explicit Types. Great for when you have Types that share common fields, but differ slightly. 

Interfaces

Unions

Like interfaces, but without any defined common fields amongst the Types. Useful when you need to access more than one disjoint Type from one Query, like a search.

https://github.com/sogko/graphql-schema-language-cheat-sheet

Relationships

Thinking in Graphs

Your API is no longer a predefined list of operations that always return the same shapes. Instead, your API is a set of Nodes that know how to resolve themselves and have links to other Nodes. This allows a client to ask for Nodes and then follow those links to get related Nodes.

  • Add a Type as a field value on another Type
  • Create resolvers for those fields on the Type

How?

Demo