GraphQL is the Better REST

What is REST?
● REST is the de-facto standard for designing Web APIs
● REST (REpresentational State Transfer) is an architectural
style for developing web services.
● REST is popular due to its simplicity and the fact that it
builds upon existing systems and features of the internet's
HTTP.

REST Design Principles
● Stateless server
● Uniform interface
● Everything is a resource
● Use HTTP verbs for CRUD actions
● Explore associations through URL structure
● Attribute filters, sorting and pagination through query
parameters
● Implement global and local searches
● Error handling using HTTP error codes
● Use JSON as data exchange format

REST APIs have shown to
be too inflexible to keep
up with the rapidly
changing requirements of
the clients that access
them.

REST Drawbacks
● Poor data discovery
● Multiple fetches are common
● Fetching extraneous data
● No query validation
● Does not handle API deprecations, additions
and changes

REST Example
● In a blogging application, an app needs to display the
titles of the posts of a specific user.
● The same screen also displays the names of the last 3
followers of that user.
Source: https://www.howtographql.com/basics/1-graphql-is-the-better-rest/

Problems with this Approach
● It took three HTTP requests to populate the
page (underfetching).
● Each request potentially returned more data
than was necessary (overfetching)
● New client data needs typically require new
endpoints (endpoint management)

Why is GitHub using GraphQL?
“GitHub chose GraphQL for our API v4 because it offers
significantly more flexibility for our integrators. The ability to
define precisely the data you want—and only the data you
want—is a powerful advantage over the REST API v3
endpoints. GraphQL lets you replace multiple REST requests
with a single call to fetch the data you specify.”
Source: https://developer.github.com/v4/

GraphQL at Netflix
“Since GraphQL allows the client to select only the data it
needs we end up fetching a significantly smaller payload. In
our application, pages that were fetching 10MB of data before
now receive about 200KB. Page loads became much faster,
especially over data-constrained mobile networks, and our
app uses much less memory. “
Source: https://medium.com/netflix-techblog/our-learnings-from-adopting-graphql-f099de39ae5f

GraphQL and REST
● Although GraphQL addresses many shortcomings of
REST, they can be easily used together.
● GraphQL API can be used as a facade with its resolvers
obtaining data using existing REST services.
● This is one way for an organization to incrementally adopt
GraphQL
Source: https://medium.com/netflix-techblog/our-learnings-from-adopting-graphql-f099de39ae5f

What is GraphQL
● 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.
● GraphQL isn't tied to any specific database or
storage engine and is instead backed by your
existing code and data.

‘Graph’ in GraphQL
● You model your business domain as a graph by
defining a schema.
● Within your schema, you define different types of
nodes and how they connect/relate to one another.

GraphQL Core Concepts
● The Schema Definition Language (SDL)
○ Queries to Fetch Data
○ Mutations to Update Data
○ Subscriptions for Real-Time Updates
● Resolvers to implement Queries, Mutations and
Subscriptions

GraphQL: Structure vs. Behavior
● Separating interface from implementation
● Interface (structure) is defined by the schema
● Implementation (behavior) is encapsulated in
resolvers.

Structure vs. Behavior in GraphQL
Schema
Resolvers
Specification
Implementation

Source: “Visual Design of GraphQL Data” by Thomas Frisendal

What is a Schema?
● The GraphQL schema defines the server’s API
● The GraphQL schema provides a clear contract
for client-server communication
● GraphQL schemas are language-agnostic
● The main components of a schema definition are
the types and their fields

Example of Types and Fields
type Post {
id: String!
title: String!
publishedAt: DateTime!
likes: Int! @default(value: 0)
blog: Blog @relation(name: "Posts")
}
type Blog {
id: String!
name: String!
description: String,
posts: [Post!]! @relation(name: "Posts")
}

GraphQL Schema Types
● Object types represent a kind of object you can fetch from your
service, and what fields it has
● A type has a name and can implement one or more interfaces
● A field has a name and a type
● GraphQL supports built-in scalar types
● An enum is a scalar value that has a specified set of possible
values
● An Interface is an abstract type that includes a certain set of
fields that a type must include to implement the interface
● Custom types can be created using scalar types, enums, other
custom types and interfaces.

Anatomy of GraphQL Custom Type
type Character {
name: String!
appearsIn: [Episode]!
}
Type Name
Field
Field of Scalar Type
Field of Array Type
Non-nullable field

Built-in Scalar Types
● Int: A signed 32‐bit integer.
● Float: A signed double-precision floating-point value.
● String: A UTF‐8 character sequence.
● Boolean: true or false.
● ID: The ID scalar type represents a unique identifier

Enumeration Types
● Special kind of scalar that is restricted to a particular set of allowed values
● Validates that any arguments of this type are one of the allowed values
● Communicates through the type system that a field will always be one of a
finite set of values
enum Episode {
NEWHOPE
EMPIRE
JEDI
}

Interfaces
interface Character {
id: ID!
name: String!
friends: [Character]
}
type Human implements Character {
id: ID!
name: String!
starships: [Starship]
totalCredits: Int
}
type Droid implements Character {
id: ID!
name: String!
primaryFunction: String
}

Defining Queries, Mutations
and Subscriptions

Query, Mutation and Subscription Types
● In addition to schema types defining the server-side domain
model, GraphQL defines special types, Query, Mutation and
Subscription
● These types define the server API in terms of domain types
● Query type specifies what queries clients can execute
● Mutation type defines create, update and delete operations
● Subscription defines the events the client can receive from the
server

Snowtooth Example
https://github.com/MoonHighway/snowtooth

GraphQL definition of type Lift
# A `Lift` is a chairlift, gondola, tram, funicular, pulley, rope tow, or other means of ascending a mountain.
type Lift {
# The unique identifier for a `Lift` (id: "panorama")
id: ID!
# The name of a `Lift`
name: String!
# The current status for a `Lift`: `OPEN`, `CLOSED`, `HOLD`
status: LiftStatus
# The number of people that a `Lift` can hold
capacity: Int!
# A boolean describing whether a `Lift` is open for night skiing
night: Boolean!
# The number of feet in elevation that a `Lift` ascends
elevationGain: Int!
# A list of trails that this `Lift` serves
trailAccess: [Trail!]!
}

GraphQL definition of type Trail
# A `Trail` is a run at a ski resort
type Trail {
# A unique identifier for a `Trail` (id: 'hemmed-slacks')
id: ID!
# The name of a `Trail`
name: String!
# The current status for a `Trail`: OPEN, CLOSED
status: TrailStatus
# The difficulty rating for a `Trail`
difficulty: String!
# A boolean describing whether or not a `Trail` is groomed
groomed: Boolean!
# A boolean describing whether or not a `Trail` has trees
trees: Boolean!
# A boolean describing whether or not a `Trail` is open for night skiing
night: Boolean!
# A list of Lifts that provide access to this `Trail`
accessedByLifts: [Lift!]!
}

GraphQL definition of enums LiftStatus and TrailStatus
# An enum describing the options for `LiftStatus`: `OPEN`, `CLOSED`, `HOLD`
enum LiftStatus {
OPEN
CLOSED
HOLD
}
# An enum describing the options for `TrailStatus`: `OPEN`, `CLOSED`
enum TrailStatus {
OPEN
CLOSED
}

GraphQL definition of API Queries against Lists and Trails
type Query {
# A list of all `Lift` objects
allLifts(status: LiftStatus): [Lift!]!
# A list of all `Trail` objects
allTrails(status: TrailStatus): [Trail!]!
# Returns a `Lift` by ìd` (id: "panorama")
Lift(id: ID!): Lift!
# Returns a `Trail` by ìd` (id: "old-witch")
Trail(id: ID!): Trail!
# Returns an Ìnt` of `Lift` objects by `LiftStatus`
liftCount(status: LiftStatus!): Int!
# Returns an Ìnt` of `Trail` objects by `TrailStatus`
trailCount(status: TrailStatus!): Int!
}

GraphQL definition of Mutations and Subscriptions
type Mutation {
"""
Sets a `Lift` status by sending `id` and `status`
"""
setLiftStatus(id: ID!, status: LiftStatus!): Lift!
"""
Sets a `Trail` status by sending `id` and `status`
"""
setTrailStatus(id: ID!, status: TrailStatus!): Trail!
}
type Subscription {
liftStatusChange: Lift
trailStatusChange: Trail
}

Snowtooth Demo
http://snowtooth.moonhighway.com/

GraphQL Queries vs. REST Queries
● REST Server define multiple query endpoints,
each with a predefined data structure
● GraphQL Server provide a single query
endpoints with a flexible query structure
● Query structure in GraphQL is defined in terms
of Schema Types discussed previously

A simple GraphQL query and its result
{
hero {
name
}
}
{
"data": {
"hero": {
"name": "R2-D2"
}
}
}

A multi-level GraphQL query
{
hero {
name
# Queries can have comments!
friends {
name
}
}
}
{
"data": {
"hero": {
"name": "R2-D2",
"friends": [
{
"name": "Luke Skywalker"
},
{
"name": "Han Solo"
},
{
"name": "Leia Organa"
}
]
}
}
}

A named query with an argument
query GetReturnOfTheJedi {
film(id: "ZmlsbXM6Mw==") {
title
director
releaseDate
}
}
{
"data": {
"film": {
"title": "Return of the Jedi",
"director": "Richard Marquand",
"releaseDate": "1983-05-25"
}
}
}

A named query with a variable argument
query GetReturnOfTheJedi($id: ID) {
film(id: $id) {
title
director
releaseDate
}
}
{ "id": filmId }
{
"data": {
"film": {
"title": "Return of the Jedi",
"director": "Richard Marquand",
"releaseDate": "1983-05-25"
}
}
}

A query with a field alias
query GetTitles {
allFilms {
films {
filmTitle: title
}
}
}
{
"data": {
"allFilms": {
"films": [
{
"filmTitle": "A New Hope"
},
{
"filmTitle": "The Empire Strikes Back"
},
{
"filmTitle": "Return of the Jedi"
},
...

Using query fragments
query GetFilmInfo {
film1: film(id: "ZmlsbXM6NA==") {
title
director
producers
}
film2: film(id: "ZmlsbXM6Ng==") {
title
director
producers
}
}
query GetFilmInfo {
film1: film(id: "ZmlsbXM6NA==") {
...info
}
film2: film(id: "ZmlsbXM6Ng==") {
...info
}
}
fragment info on Film {
title
director
producers
}

@include directive
query GetTitles($includeDirector: Boolean!) {
allFilms {
films {
filmTitle: title
director @include(if: $includeDirector)
}
}
}
{
"data": {
"allFilms": {
"films": [
{
"filmTitle": "A New Hope",
"director": "George Lucas"
},
{
"filmTitle": "The Empire Strikes Back",
"director": "Irvin Kershner"
},
{
"filmTitle": "Return of the Jedi",
"director": "Richard Marquand"
},
...

Mutations Defined
● The purpose of mutations is
○ Creating new data
○ Updating existing data
○ Deleting data
● Syntax for mutations is similar to that of queries
○ name
○ arguments
○ return object with its fields

Named mutation with parameters
mutation CreateReviewForEpisode($ep: Episode!,
$review: ReviewInput!) {
createReview(episode: $ep, review: $review) {
stars
commentary
}
}
{
"ep": "JEDI",
"review": {
"stars": 5,
"commentary": "This is a great movie!"
}
}
{
"data": {
"createReview": {
"stars": 5,
"commentary": "This is a great
movie!"
}
}
}

Resolvers Defined
● Resolvers implement the API
● Each field in a GraphQL schema is backed by a
resolver
● Each resolver knows how to fetch the data for
its field.

GraphQL resolvers for API Queries against Lists and Trails
module.exports = {
allLifts: (root, { status }, { lifts }) => {
if (!status) {
return lifts
} else {
var filteredLifts = lifts.filter(lift => lift.status === status)
return filteredLifts
}
},
allTrails: (root, { status }, { trails }) => {
if (!status) {
return trails
} else {
var filteredTrails = trails.filter(trail => trail.status === status)
return filteredTrails
}
},
Lift: (root, { id }, { lifts }) => {
var selectedLift = lifts.filter(lift => id === lift.id)
return selectedLift[0]
},
...

Resolver definitions continued
...
Trail: (root, { id }, { trails }) => {
var selectedTrail = trails.filter(trail => id === trail.id)
return selectedTrail[0]
},
liftCount: (root, { status }, { lifts }) => {
var i = 0
lifts.map(lift => {
lift.status === status ?
i++ :
null
})
return i
},
trailCount: (root, { status }, { trails }) => {
var i = 0
trails.map(trail => {
trail.status === status ?
i++ :
null
})
return i
}
}

Resolver Parameters
Resolvers get four parameters:
● Root - argument in each resolver call is simply the result of the previous
call (initial value is rootValue from the server configuration)
● Args - carries the parameters for the query
● Context - an object that gets passed through the resolver chain that each
resolver can write to and read from
● Info - an AST representation of the query or mutation

Resolvers for the field of the Lift type
module.exports = {
trailAccess: (root, args, { trails }) => root.trails
.map(id => trails.find(t => id === t.id))
.filter(x => x)
}

GraphQL definition of API Queries against Lists and Trails
type Mutation {
"""
Sets a `Lift` status by sending `id` and `status`
"""
setLiftStatus(id: ID!, status: LiftStatus!): Lift!
"""
Sets a `Trail` status by sending `id` and `status`
"""
setTrailStatus(id: ID!, status: TrailStatus!): Trail!
}
type Subscription {
liftStatusChange: Lift
trailStatusChange: Trail
}

Resolvers for Mutations
module.exports = {
setLiftStatus: (root, { id, status }, { lifts, pubsub }) => {
var updatedLift = lifts.find(lift => id === lift.id)
updatedLift.status = status
pubsub.publish('lift-status-change', { liftStatusChange: updatedLift })
return updatedLift
},
setTrailStatus: (root, { id, status }, { trails, pubsub }) => {
var updatedTrail = trails.find(trail => id === trail.id)
updatedTrail.status = status
pubsub.publish('trail-status-change', { trailStatusChange: updatedTrail })
return updatedTrail
}
}

Resolvers for Subscriptions
module.exports = {
liftStatusChange: {
subscribe: (root, data, { pubsub }) => pubsub.asyncIterator('lift-status-change')
},
trailStatusChange: {
subscribe: (root, data, { pubsub }) => pubsub.asyncIterator('trail-status-change')
}
}

The GRANDstack
GRANDstack is a full-stack development
integration for building graph-based
applications.

GRANDstack Technologies
● GraphQL – a query language for APIs and a runtime for
fulfilling those queries with your existing data
● React – a JavaScript library for building user interfaces
● Apollo Client – a fully-featured, production-ready
caching GraphQL client for every server or UI framework
● Neo4j Database – a graph database that is
ACID-compliant and built to store and retrieve
connected data

GraphQL APIs have a strongly typed schema
A GraphQL schema is the backbone of every
GraphQL API. It clearly defines the operations
(queries, mutations and subscriptions)
supported by the API, including input arguments
and possible responses. The schema is an
unfailing contract that specifies the capabilities
of an API.

GraphQL APIs have a strongly typed schema
Developers don’t have to manually write API
documentation any more — instead it can be
auto-generated based on the schema that
defines the API

No more overfetching and underfetching
Clients can retrieve exactly the data they need
from the API. They don’t have to rely on REST
endpoints that return predefined and fixed data
structures. Instead, the client can dictate the
shape of the response objects returned by the
API.

GraphQL enables rapid product development
Thanks to GraphQL, client libraries (like Apollo,
Relay or Urql) frontend developers are getting
features like caching, realtime or optimistic UI
updates basically for free.

GraphQL enables rapid product development
● Schema-driven development is a process where
a feature is first defined in the schema, then
implemented with resolver functions.
● Tools like GraphQL Faker mocks the entire
GraphQL API (based on its schema definition),
so frontend and backend teams can work
completely independently.

Support for multiple server-side languages
● A GraphQL server can be implemented in any
programming language that can be used to build
a web server.
● Next to Javascript, there are popular reference
implementations for Ruby, Python, Scala, Java,
Clojure, Go and .NET.

Composing GraphQL APIs
● Schema stitching is combining and connecting
multiple GraphQL schemas (or schema
definitions) to create a single GraphQL API.
● Thanks to schema stitching, clients only deal
with a single API endpoint and all complexity of
orchestrating the communication with the
various services is hidden from the client.

Rich open-source ecosystem
● When it came out, the only tooling available for
developers to use GraphQL was the graphql-js
reference implementation, a piece of
middleware for Express.js, and the GraphQL
client Relay (Classic).

GraphQL Clients
● FetchQL
● GraphQL Request
● Apollo Fetch
● Lokka
● Micro GraphQL React
● URQL
● Apollo Client
● Relay Modern

GraphQL Tools
● Prisma - Simplified Database Access
● GraphQL Faker - Mock your future API or
extend the existing API with realistic data
● GraphQL Playground - GraphQL IDE
● Graphql-config - IDE configuration

GraphQL is the Better REST

Recommended

Recommended

More Related Content

More from Data Works MD

More from Data Works MD (11)

Recently uploaded

Recently uploaded (20)

GraphQL is the Better REST