Max Panas (Web Developer @Agile Actors) and Stelios Charbalis (Software Engineer @Agile Actors) present GraphQL and how it compares to traditional REST API design at GreeceJS Meetup #14 (Athens, June 15, 2016).

1. GraphQL vs REST
Maximilianos GJ Panas
Software Engineer@AgileActors
@mgjp_
Stelios Charmpalis
Software Engineer@AgileActors
@SteliosHarb
AgileActors Blog

2. REpresentational State Transfer
HTTP verbs(GET, POST, PUT, DELETE)
Resource Based URLs - Endpoints (/ᴀ各lms/24)
REST(ful) API

3. 22. GET /characters/34
23. {
24. "id": 34,
25. "name": "Luke Skywalker",
26. "birthYear": "1",
27. "eyeColor": "blue",
28. "gender": "male",
29. "hairColor": "blond",
30. "height": 172,
31. "mass": 77,
32. "skinColor": "fair"
33. }
34.
35.
18. [
19. "/characters/34",
20. "/characters/35"
21. ]
36.
37.
38.
39.
40.
Retrieves the info about the `characters` with ID `34`

5. It is a period of civil war....
GET /films/1
{
"id": 1,
"title": "A New Hope",
"episodeID": 4,
"openingCrawl": "It is a period...",
"poster": "http://...",
"releaseDate": "2002‐05‐16",
"created": "2014‐12‐20T10:57:57.886Z",
"edited": "2014‐12‐20T20:18:48.516Z"
}
PM (Project Manager)
Film Card using a RESTful API
A New Hope
Episode 4

6. It is a period of civil war....
Characters
{
"id": 1
"title": "A New Hope",
...
}
# 4 different queries
1. GET /films/1
2. GET /films/1/characters
3. GET /character/34
4. GET /character/35
# 1 Request ‐ Add boolean query string
GET /films/1?include_character_details=true
# 1 Request ‐ New custom endpoint
GET /films_with_character_details/1
Film Card using a RESTful API
A New Hope
Episode 4
Luke Skywalker
C­3PO

7. /* JSON Response */
{
"id": 1,
"title": "A New Hope",
"episodeID": 4,
"openingCrawl": "It is a period...",
"poster": "http://...",
"releaseDate": "2002‐05‐16",
"created": "2014‐12‐20T10:57:57.886Z",
"edited": "2014‐12‐20T20:18:48.516Z",
"characters": [
{
"id": 35,
"name": "C‐3PO",
"birthYear": "112BBY",
"eyeColor": "yellow",
"gender": "n/a",
"hairColor": "n/a",
"height": 167,
"mass": 75,
"skinColor": "gold",
"avatar": "http://..."
}, {
...
}]
}
/* JSON Response */
{
"title": "A New Hope",
"episodeID": 4,
"openingCrawl": "It is a period...",
"poster": "http://...",
"characters": [
{
"name": "C‐3PO",
"avatar": "http://..."
}, {
...
}]
}
SIMPLIFY JSON RESPONSE

8. /* GraphQL Request */
{
title
episodeID
openingCrawl
poster
characters {
name
avatar
}
}
/* JSON Response */
{
"title": "A New Hope",
"episodeID": 4,
"openingCrawl": "It is a period...",
"poster": "http://...",
"characters": [
{
"name": "C‐3PO",
"avatar": "http://..."
}, {
...
}]
}
A GRAPHQL REQUEST

9. Eliminate Overfetching
Eliminate Underfetching
Be Declarative
Increase Product Developer Autonomy
Natively Support Versioning
CORE GOALS

10. HELLO WORLD
{
bestFilm {
title
}
}
{
"bestFilm": {
"title": "The Empire Strikes Back"
}
}

11. ARGUMENTS
{
film(id: 1) {
title
}
}
{
"film": {
"title": "A New Hope"
}
}

12. COMPLEX QUERIES
{
film(id: 1) {
title
poster {
width
height
url
}
}
}
{
"film": {
"title": "A New Hope",
"poster": {
"width": 300,
"height": 300,
"url": "https://..."
}
}
}

13. NODES WITHIN NODES
{
film(id: 1) {
title
poster(size: 1000) {
width
height
url
}
}
}
{
"film": {
"title": "A New Hope",
"poster": {
"width": 1000,
"height": 1000,
"url": "https://..."
}
}
}

14. ALIASES
{
film(id: 1) {
title
regularPic: poster(size: 500) {
width
height
url
}
retinaPic: poster(size: 1000) {
width
height
url
}
}
}
{
"film": {
"title": "A New Hope",
"normalPic": {
"width": 500,
"height": 500,
"url": "https://..."
},
"retinaPic": {
"width": 1000,
"height": 1000,
"url": "https://..."
}
}
}

15. NESTED QUERIES
{
film(id: 1) {
title
characters {
name
films {
title
characters {
name
}
}
}
}
}
{
"film": {
"title": "A New Hope",
"characters": [{
"name": "Yoda"
"films": [{
"title": "The Empire Strikes Back",
"characters": [{
"name": "Luke Skywalker"
}, {
"name": "Han Solo"
}]
}, {
"title": "Return of the Jedi",
"characters": [{
"name": "C‐3PO"
}, {
...
}]
}]

16. }, {
HOW GRAPHQL
WORKS
User-Deᴀ各ned type system - "schema"
Data Universe is deᴀ各ned and connected on the server
Multiple Back-end services exposed through a single
controlled API
The client requests for exactly what it wants

17. TYPE SYSTEM (SCHEMA)
type Root {
bestFilm: Film
film(id: Int!): Film
}
type Film {
title: String
poster(size: Int = 300): Picture
characters: [Person]
}
type Person {
name: String
films: [Film]
}
type Picture {
width: Int
height: Int
url: String
}

18. GRAPHQL-JS
const Root = new GraphQLObjectType({
name: 'Root',
description: 'The starting point of your GraphQL query',
fields: () => ({
bestFilm: {
type: Film,
resolve: (root, args, context) => api.getTop('film')
.then(id => api.getFilm(id)),
},
film: {
type: Film,
args: { id: { type: new GraphQLNonNull(GraphQLInt) } },
resolve: (root, args, context) => api.getFilm(args.id),
},
}),
});

19. Demo with GraphiQL

20. GraphQL is not bound by any client framework
Ways of using it on the client
Relay (Speciᴀ各cally for React)
Lokka (Simplest lib, can be used with anything)
Others (Apollo, XHR, etc.)
Queries can easily be broken apart andmerged together
again
Declare exactly what your data requirements are on the
component layer
THE CLIENT STORY

21. GraphQL is a speciᴀ各cation of a communication protocol, not a storage
system, not a library
GraphQL is not tied to a speciᴀ各c language or framework
GraphQL does not allow clients to arbitrarily query your database(s)
GraphQL does not require a speciᴀ各c backend storage system
Security: Authentication is handled the same way as in REST
POSSIBLE MISCONCEPTIONS

22. Handling Resource intensive Queries on the Backend
- facebook/Dataloader
Handling errors in resolvers
- khadira/graphql-errors
Granular Control on querying
- @defer, @async, @stream
Live Queries
- Subscriptions
PRACTICAL PROBLEMS

23. GraphQL Introduction
GraphQL
Learn GraphQL
Zero to GraphQL in 30 Minutes – Steven Luscher
From REST to GraphQL
Validation and User Errors in GraphQL Mutations
Presentation built with Spectacle
USEFUL LINKS

24. THANK YOU!
Any questions?