This document provides an introduction and overview of GraphQL. It begins with an example comparing making multiple REST API calls to fetch related data versus making a single GraphQL query. Key points covered include GraphQL's characteristics like being a query language that is agnostic to storage and returning only requested data, advantages over REST like fewer requests and tailored responses, and potential drawbacks like increased coupling. The document demonstrates GraphQL syntax and concepts like queries, mutations, fragments, and directives. It also discusses GraphQL adoption by companies like Facebook and how Liveperson evaluates it.

1. GraphQL Intro
Nir Levy, Jan 17

2. Agenda
● What is GraphQL
● GraphQL characteristics and syntax
● Advantages over REST
● GraphQL drawbacks
● GraphQL in Liveperson
● Demo
● Further reading
● Questions

3. Let’s start with an example
● Say you have an API for music albums and songs:
● And now you want to get all of an artist’s albums with their songs lists
Song:
{
“id” : 116
“artist”: “David Bowie”,
“name”: “Time”,
“album” : “Aladdin Sane”,
“duration”: “5:15”,
“trackNumber”: 6,
...
}
Album:
{
“id” : 321
“artist”: “David Bowie”,
“name”: “Aladdin Sane”,
“releaseYear”: 1973,
“songIDs”: [111,112,113,114,....],
...
}

4. Example continued
GET /artist/1
GET /album/321
GET /song/111
GET /song/112
…
…
GET /song/120
GET /album/322
GET /song/211
GET /song/212
…
…
GET /song/220
...
Requires many requests
Each request returns much more data than you
need
● Other option - ad-hoc API for album with
songs
○ But adding API per need might end up
with way too many APIs
○ And you’d still get more data than you
need

5. REST Limitations
● resource-centric: many endpoints
● The endpoints are often organized the way they’re stored in DB,
not the way they’re retrieved by clients
● large (and fixed) responses
● Getting a complete response requires multiple requests
● We would like to get on a single request
● ALL the data that we need, from several resources
● ONLY the data that we need - no large responses with redundant
fields

6. What is GraphQL
● A data query language
● Completely agnostic to the underlying storage or
programming language
● Invented and used by Facebook since 2012
● Open sourced on 2015
● Re-defines the client-server relations
● Moving the power to the client
● He decides what to fetch, not the server

7. Who uses GraphQL

8. What is GraphQL
Client request
album (artist: “David Bowie”
name: “Heroes”) {
releaseYear
songs {
trackNumber
name
duration
}
}
Query name
arguments
Selection set
to return
Schema
schema {
query: {
album(artist: String!
name: String!):Album
}
Album: {
id: ID
name: String
releaseYear: Integer
artist: String
songs: [Song]
}
Song: {
id: ID
name: String
duration: String
trackNumber: Integer
}
}
Response
{
"album": {
"releaseYear": 1977,
"songs": [
{
"trackNumber": 1,
"Name": "beauty and the beast",
"Duration": "3:32"
},
{
"trackNumber": 2,
"Name": "Joe the Lion",
"Duration": "3:05"
},
…
]
}
}

9. GraphQL Characteristics
● GraphQL describes what data to fetch rather than actual queries to a
database.
● A GraphQL server interprets these calls and then queries the storage
layer, using the schema and resolvers.
● Entirely agnostic to the storage layer, can be also used as a proxy
forward API calls.
● Contains introspection features to expose the server’s schema and
objects.

10. Resolvers
● The schema contains the objects the server returns.
● Each object can consist of scalar fields (int, string etc.) or other
objects.
● Each object in the schema should be provided with a resolver.
● The resolver is a piece of code that does the actual work - fetches
the results from the storage layer.
● GraphQL server will take care of combining the objects and returning
only the selection set fields.

11. Resolvers
● When running the query, album resolver will fetch the album
according to the provided artist and name
● Albums in DB contain song Ids - the song resolver will fetch the
songs according to the Ids
● GraphQL server will then combine the results and return only the
requested fields
● There are several solutions for batching and caching to make the
fetching more efficient
Schema
schema {
query: {
album(artist: String!
name: String!):Album
}
Album: {
id: ID
name: String
releaseYear: Integer
artist: String
songs: [Song]
}
Song: {
id: ID
name: String
duration: String
trackNumber: Integer
}
}
Songs Storage
Song:
{
“id” : 116
“artist”: “David Bowie”,
“name”: “Time”,
“album” : “Aladdin Sane”,
“duration”: “5:15”,
“trackNumber”: 6,
...
}
Albums Storage
Album:
{
“id” : 321
“artist”: “David Bowie”,
“name”: “Aladdin Sane”,
“releaseYear”: 1973,
“songIDs”: [111,112,113,114,....],
...
}

12. GraphQL Basic Syntax
● Two types of Operations
○ Query: read only fetch
○ Mutation: write and fetch
● Can contain arguments
● Selection Sets: a subset of the fields on an object.
○ Can be objects as well
○ Defines the returned object’s structure
{
getAlbum(artist: 123) {
name
releaseYear
songs {
name
duration
}
}
}

13. Mutations
● Mutations are yet another kind of queries
● By convention, we use query for read only operations, and mutation for
persist operations (create/update/delete/patch)
● Mutation also has a returned value, just like query

14. API Versioning in GraphQL
● When the client can’t control the returned data, any change can be a
breaking one
● Any change that is considered as a breaking one, requires a new API
version
● In contrast, GraphQL only returns the data that's explicitly requested
● New capabilities can be added via new new fields
○ Which will not be consumpt by the client until explicitly requested
● The common practice is to avoid changing existing fields, and serving a
versionless API.
● There’s a deprecation mechanism to handle obsolete fields

15. So Why choose GraphQL over REST?
● Single endpoint - easier to scale
● Tailored responses - client gets only what he wants
● Fewer round trips - can return several related resources together
● Backwards compatibility - the client decides the response structure,
knows exactly what to expect
● Introspective - GraphQL has a native and highly extensible schema
and type system

16. GraphQL drawbacks
● Coupling between entities is inherent - The schema needs to know all
types
● Still relatively new
● No clear best-practices/standards
● Frameworks and resources are less mature than REST or other
industry standards

17. GraphQL in Liveperson
● Audit Trail API is built using GraphQL
● We evaluate the option to build Account Config 2.0 using GraphQL
based APIs

18. DEMO
https://www.graphqlhub.com

19. Advanced Syntax - Fragments
● Fragments are aliases for a bundle of fields.
● Fields in fragments are added at the same level of invocation as
adjacent fields.
● Syntax- prefixed with ...
Query
{
album(id: 1) {
name
...customFields
}
}
fragment customFields on Album {
releaseYear
songs {
name
duration
}
}
Response
{
"album": {
"name": “heroes”,
"releaseYear": 1977,
"songs": [
{
"Name": "beauty and the beast",
"Duration": "3:32"
},
{
"Name": "Joe the Lion",
"Duration": "3:05"
},
…
]
}
}

20. Advanced Syntax - Directives
● Directives alter execution behavior and can be used to conditionally
include (@include) or exclude (@skip) fields.
Request
query getSong(fullDetails: Boolean id: Int) {
name
... @include(if: $fullDetails) {
duration
album
}
}
}
// response when $fullDetails resolves to false
{
"getSong": {
"name": "Time"
}
}
// response when $fullDetails resolves to true
{
"getSong": {
"name": "Time",
"album": "Aladdin Sane",
“duration”: “5:15”
}
}

21. Further reading
● https://github.com/chentsulin/awesome-graphql - github repo with
many links to tutorials, libraries in various languages, blogs, videos and
more
● http://graphql.org/learn
● https://www.graphqlhub.com - playground on various public GraphQL
API. good place to learn the syntax

22. Questions

23. Thank You