Better APIs with GraphQL

Better APIs
with GraphQL
Josh Price
github.com/joshprice
@joshprice

Agenda
• Understand GraphQL and why you'd use it
• Build a simple schema
• Run queries against the schema
• Understand important GraphQL concepts
• Summarise client options

Common Problems
Overfetching
Underfetching

Internal APIs have
strong contracts
between
client and server

What is GraphQL?
• Language for deﬁning schemas, types & queries
• Developed by Facebook in 2012
• Used to improve mobile app performance
• Serves 300 billion+ requests per day

Open Source
• Open sourced in July 2015
• Speciﬁcation
• facebook.github.io/graphql
• Reference Implementation
• github.com/graphql/graphql-js
• Relay released in August 2015

GraphQL Server Implementations
• JavaScript reference
• Ruby / Python / PHP
• Java / Scala (Sangria)
• .NET
• Elixir / Go / Haskell / OCaml
• etc...

GraphQL Misconceptions
• Not really about "graphs"
• A speciﬁcation for client/server interaction
• Language independent
• Assumes nothing about:
• transport
• message protocol
• data store

Exhibit A: REST API
Fetch user name and friends names with 2 requests
GET /users/1
GET /users/1/friends
or a single request
GET /users/1/friends?include=user.name,friend.name

Exhibit B: GraphQL API
{ "data": {
user(id: 1) { "user": {
name "name": "Josh",
friends(first: 1) { "friends": [{
name "name": "James"
} }]
} }
} }

Query and Mutation Roots
type Query {
me: User
user(id: Int): User
}
type Mutation {
createPost(title: String!): Post
createComment(message: String!): Comment
}

Object Types and Enums
type User {
name: String
profilePicture(size: Int = 50): ProfilePicture
friends(first: Int, orderBy: FriendOrder): [User]
}
enum FriendOrder { FIRST_NAME, LAST_NAME, IMPORTANCE }

More Types
type ProfilePicture {
width: Int
height: Int
url: String
}
type Event {
name: String
attendees(first: Int): [User]
}

Simplest Query
{
me {
name
}
}
{
"data": {
"me": {
"name": "Josh Price"
}
}
}

Deeply Nested Query
{ {
me { "data": {
name "name": "Josh Price",
profilePicture { "profilePicture": {
url "url": "http://cdn/josh_50x50.png"
} },
friends(first: 1) { "friends": [{
name "name": "James Sadler"
} }],
events(first: 1) { "events": [{
name "name": "Afterparty!",
attendees(first: 1) { "attendees": [{
name "name": "Jenny Savage"
} }]
} }]
} }
} }

Resolvers
• Your own functions
• Could use in memory data
• Call any data store
• Proxy REST APIs
• Call existing services
• GraphQL doesn't care
• Resolver "Middleware" is possible (Auth, Logging, etc)

User Type with JS Resolvers
new GraphQLObject({
type: "User",
fields: {
name(user) {
return user.name
},
profilePicture(user, {size}) {
return getProfilePicForUser(user, size);
},
friends(user) {
return user.friendIDs.map(id => getUser(id));
}
}
});

Mutations Modify Data
mutation {
acceptFriendRequest(userId: 345124) {
user {
friends { count }
}
}
}
mutation {
rsvpToEvent(eventId: 134624, status: ATTENDING) {
event {
invitees { count }
attendees { count }
}
}
}

Setup GraphQL Express
import { Schema } from './schema.js';
import graphqlHTTP from 'express-graphql';
import express from 'express';
const app = express();
app.get('/', function(req, res) {
res.redirect('/graphql');
});
app.use('/graphql', graphqlHTTP({ schema: Schema, graphiql: true }));
app.listen(3000);

Relay
• Each view component declares query fragment
• Relay batches all data req'ts for render tree
• Sends single query
• Handles caching using global IDs
• Relies on schema conventions for metadata

Client-Side Alternatives
• ApolloStack Client
• React + Native
• Angular 2
• Redux support
• Lokka
• Simple

Gotchas
• Arbitrary Queries
• Could be slow if deeply nested (friends of friends...)
• Complexity analysis
• Query depth
• Batching resolvers
• Data Loader (JS)
• GraphQL Batch (Ruby)

When to use?
• Use for internal APIs ﬁrst, or limited external use
• Improve mobile (and desktop performance)
• Github has exposed their API externally
• Be careful exposing this to the world!
• Don't allow arbitrary queries from unknown clients

GraphQL Ecosystem
Evolving Quickly

GraphQL Backend as a Service
• reindex.io
• graph.cool
• scaphold.io

Future - GraphQL Spec
• Push: Apps should reﬂect current state of world
• Subscriptions + Reactive Backend + RethinkDB
• Defer
• Stream
• Live queries
• GraphQL CATS

Subscriptions
subscription {
createCommentSubscribe(storyId: $id) {
comment {
...FBCommentFragment
}
}
}

Defer Directive
{ {
feed { "feed": {
stories { "stories": [{
author { name } "author": { "name": "Lee Byron" },
title "title": "GraphQL is the Future"
comments @defer { }, {
author { name } "author": { "name": "Josh Price" },
comment "title": "REST is old school"
} }]
} }
} }
}

Defer - Comments arrive
{ {
feed { "path": ["feed", "stories", 0, "comment"],
stories { "data": [{
author { name } "author": { "name": "Joe Bloggs" },
title "comment": "That blew my mind!"
comments @defer { }, {
author { name } "author": { "name": "Jenny Savage" },
comment "comment": "I love it"
} }]
} }
}
}

Stream Directive
{ {
feed { "feed": {
stories @stream { "stories": []
author { name } }
title }
comments @defer {
author { name }
comment
}
}
}
}

Stream - First Story
{ {
feed { "path": ["feed", "stories", 0],
stories @stream { "data": [{
author { name } "author": { "name": "Joe Bloggs" },
title "title": "That blew my mind!"
comments @defer { }]
author { name } }
comment
}
}
}
}

Live Directive
{ {
feed { "feed": {
stories { "stories": [{
author { name } "author": { "name": "Lee Byron" },
title "title": "GraphQL is the Future",
likeCount @live "likeCount": 9
} }]
} }
} }

Live - Likes update on backend
{ {
feed { "path": ["feed", "stories", 0, "likeCount"],
stories { "data": 10
author { name } }
title
likeCount @live
}
}
}

Resources
• graphql.org
• Github
• graphql/graphql-js
• graphql/express-graphql
• Steve Luscher talk Zero to GraphQL
• Awesome GraphQL (chentsulin/awesome-graphql)

Better APIs with GraphQL

More Related Content

What's hot (20)

Viewers also liked (18)

Similar to Better APIs with GraphQL (20)

Recently uploaded (20)

Better APIs with GraphQL