Slides from presentation, I've made on the BuildStuff LT 2018. Here I'm talking about issues, many people have found when using RESTful APIs and how GraphQL addresses them. Also I'm trying to cover the tradeoffs made by the standard, solutions proposed by different implementations and some ideas for the future.

1. AN ELEGANT WEAPON...
FOR MORE CIVILIZED AGE

2. INTRODUCTION
Bartosz Sypytkowski
▪ @Horusiath
▪ b.sypytkowski@gmail.com
▪ bartoszsypytkowski.com

3.  REST: what is it all about...
 ... what problems does it have...
 ... and how GraphQL aims to solve them...
 ... at what cost...
 ... what can we do with it now ...
 ... and what could we hope for in the future.
AGENDA

4. what is it all about...
 resources ≠ operations
 CRUD over HTTP Methods
 utilization of HTTP status codes
 stateless

5. GET /documents/{id}
POST /documents/
PUT /documents/{id}
PATCH /documents/{id}
DELETE /documents/{id}
RESOURCES,
NOT OPERATIONS

6. QUIZ TIME!

7. WEBSOCKETS
What HTTP method will you use to
update a resource over websockets?

9. UNDER
FETCHING
async function getPostWithComments(postId) {
var post = await http.get('/posts/{postId}');
/* GET /posts/4277
{
"id": 4277,
"authorId": 345,
"title": "REST - why we cannot have nice things?",
"content": "a very long text"
}
*/
post.comments = await http.get('/posts/{postId}/comments');
/* GET /posts/4277/comments
[]
*/
return post;
}

10. OVER
FETCHING async function getPostTitle(postId) {
var post = await http.get('/posts/{postId}');
/* GET /posts/4277
{
"id": 4277,
"authorId": 345,
"title": "REST - why we cannot have nice things?",
"content": "a very long text"
}
*/
return post.title;
}

11. A (DOUBTFUL)
SOLUTION
 Works in limited scope
 Non-trivial to make it work right
 Risky (you may accidentally expose more than desired)
/user/{id}/posts?include=comments

12. SUMMARY
 not quite stateless
 not quite a standard
 strictly limited to HTTP request/response
 schema-less
 not self-descriptive
 hard to correlate entities from different
endpoints
 versioning
 under and overfetching

13.  Swagger
 HATEOAS
 JSON-Schema
 RAML
 RDSL
 ODATA
 JWT
 Introspected REST
 whatever else is trendy this week...
SOLUTIONS
?

17. GraphQL is a query language for APIs and a runtime for
fulfilling those queries with your existing data.
GraphQL provides a complete and understandable
description of the data in your API, gives clients the power
to ask for exactly what they need and nothing more, makes
it easier to evolve APIs over time, and enables powerful
developer tools.

18. It has specs...
... so it keeps clear
expectations.
IT'S A
STANDARD

19. WHO IS USING IT?

20. HOW DOES
IT LOOK
LIKE?
Query:
query {
article(id: ”1337”) {
id
title
author {
...fullName
}
created
comments {
author {
...fullName
}
created
}
}
}
fragment fullName on User {
firstName
lastName
}
Result:
{
"id": “1337”,
"title": "Horse steroids - guide for athletes",
"author": {
"firstName": "Andy",
"lastName": "Greenberg"
},
"created": "2015-05-22T14:56:29.000Z",
"comments": [
{
"author": {
"firstName": "Sam",
"lastName": "Gonagal"
},
"created": "2015-05-22T14:56:34.000Z"
},
{
"author": {
"firstName": "Chris",
"lastName": "McDonald"
},
"created": "2016-05-22T14:56:34.000Z"
}
]
}

21. CONSUMER
SIDE
 Query for readonly actions.
 Mutation for anything that affects the state.
 Subscription for continuous stream of data.

22. Ask for GraphQL schema using GraphQL
query language.
query AllTypesWithFields {
__schema {
types {
name
fields {
name
type {
name
}
}
}
}
}
INTROSPECTION API

23. DEMO

24. GRAPHQL
ON THE
CLIENT
SIDE
Relay
 originally
developed in
Facebook
 quite opinionated:
requires a separate
set of constraints
on top of your
GraphQL schema
 thightly integrated
with React stack
 fast!
Apollo
 easier to learn
 tons of plugins
 easy to integrate
with other
technologies ie.
Redux or Angular

25. APOLLO
const FeedWithData = graphql(gql`
{
feed (type: TOP, limit: 5) {
repository {
owner { login }
name
}
postedBy { login }
}
}
`)(Feed);
function Feed({ data }) {
return (
<View>
<Text style={styles.title}>GitHunt</Text>
{ data.feed.map((item) =>
<View style={styles.feedItem}>
<Text style={styles.entry}>
{item.repository.owner.login}/{item.repository.name}
</Text>
<Text>Posted by {item.postedBy.login}</Text>
</View>) }
</View>
);
}

26. TIME
TO
STOP
Let's speak about
downsides for a
while

27. HOW TO OPTIMIZE?

28. N+1
SELECTS
query CustomersAndTheirProducts {
customers(first: 20) {
firstName
lastName
orders {
totalPrice
orderLines {
quantity
product {
name
price
}
}
}
}
}
const resolvers = {
query: {
customers: ({first}) => {
return db.customers.take(first);
}
},
Customer: {
orders: (customer) => {
return db.orders
.where({customerId:
customer.id});
}
}
}
Client request: Server implementation (JS)

29. FSHARP.DATA.GRAPHQL
Client
Server
Query Variables
Schema Compilation
(Runtime)
Query Execution Plan Query Evaluation

30. HOPE FOR
THE
FUTURE
1. Move Schema “compilation” to compile
time
2. Execution plan caching and JIT
compilation

31. Expose query tree /
execution plan at
resolver level.
N+1 SELECTS
SOLUTION #1

32. Delay and batch resolver calls.
N+1 SELECTS
SOLUTION #2 const ordersLoader = new DataLoader((customerIds) =>
db.orders.whereIn(‘customerId’, customerIds));
const resolvers = {
query: {
customers: ({first}) => {
return db.customers.take(first);
}
},
Customer: {
orders: (customer) => {
return ordersLoader.load(customer.id);
}
}
}

33. What risks do they introduce?
1. DoS-ing the server.
2. Client needs to send a huge
query.
BIG QUERIES

34. QUERY
COMPLEXITY
ANALYSIS
Github example
https://developer.github.com/v4/guides/resource-limitations/

35. PERSISTED
QUERIES
Static / Dynamic
{
"documentId": 391958033,
"data": {
"hero": {
"name": "Han Solo",
"friends": [
{
"name": "Luke Skywalker"
},
{
"name": "Leia Organa"
},
{
"name": "R2-D2"
}
]
}
}
}

36. Sending all data at once can
take time…
HUGE REPLIES

37. DIRECTIVE:
@defer
Query:
query {
article(id: ”1337”) {
title
author {
firstName
}
comments @defer {
author {
firstName
}
created
}
}
}
Result (initial):
{
"data": {
"article": {
"title": "Horse steroids - guide for athletes",
"author": {
"firstName": "Andy"
},
"comments": null
}
}
}
Result (patch):
{
"path": ["article", "comments"],
"data": [
{
"author": {
"firstName": "Sam"
},
"created": "2015-05-22T14:56:34.000Z"
},
{
"author": {
"firstName": "Chris"
},
"created": "2016-05-22T14:56:34.000Z"
}
]
}

38. CAPABILITY-
ORIENTED
DOMAIN
DESIGN.

39. GRAPHQL
VS.
ODATA

40. ODATA Perfect use case

41. ODATA Perfect use case
▪ Data aggregation
▪ Data management: rich filtering, sorting and pagination.
▪ Part of existing REST model.

42. GRAPHQL Perfect use case (xD)

43. GRAPHQL Perfect use case
▪ Multilayered object tree domain model
▪ Low-bandwidth / high-latency networks (e.g. mobile)
▪ Public API for 3rd party consumers

44. SUMMARY

45. THANK YOU