Three years ago, with the release of the GraphQL specification, Facebook took a fresh stab at the topic of "API design between remote services and applications." The key aspects of GraphQL provide a common, schema-based, domain-specific language and flexible, dynamic queries at interface boundaries. In the talk, I'd like to compare GraphQL and REST and showcase benefits for developers and architects using a concrete example in application and API development, data source and system integration.

1. The new "Lingua Franca" for API Development
"What you want is what you get"

2. About.Me/mhunger
Michael Hunger
(Director of) Developer Relations Engineering,
Neo4j
jexp.de/blog | @mesirii | github.com/jexp

3. I'm no expert in RESTful API design,
development and deployment.
If in doubt ask the experts, like Stefan, Oliver,
Jim, Ian, ...
I did a decent share of GraphQL though.

4. You ?
Have you heard of GraphQL?
Have you used GraphQL?
Did you attend the talks from Lars Röwekamp
or Manuel Mauky at OOP?

5. Some wise Words on Choosing an API Style
• Context matters
• API design styles are just tools
• Make an informed choice
• Choice will affect many aspects
(impl, dev-experience, lifecycle)
https://apihandyman.io/and-graphql-for-all-a-few-things-to-think-about-before-blindly-dumping-rest-for-graphql/

6. Ways to Build Remote APIs
API Design Styles

7. (by Manuel Mauky)

8. Remote API Techniques
•RPC (gRPC, CORBA)
•WS-* (SOAP)
•Publish / Subscribe
•Streaming Events (Kafka, Event Store)
•REST
•GraphQL

9. What?

10. What is GraphQL ?
GraphQL is an API query language
The "Graph" is the application domain model
Specification & Reference Implementation
Expressive, extensible nested expressions

11. What is GraphQL not?
GraphQL is not a (graph) database query language
GraphQL is not a RESTful API
GraphQL is not a Silver Bullet

12. Why?

13. Why GraphQL?
We were frustrated with the differences between the data we
wanted to use in our apps and the server queries they
required.
GraphQL was our opportunity to rethink mobile app data-
fetching from the perspective of product designers and
developers.
It moved the focus of development to the client apps, where
designers and developers spend their time and attention.
GraphQL, a data query language. Post by Lee Byron

14. Origins

15. GraphQL - Origins?
•Facebook 2012
• efficient queries for
mobile clients
• minimize latency &
roundtrips
• "get what you need"
• pragmatic development
• Open Sourced 2015
• Language Specificiation
• Reference Implementation
• Quickly Growing Community
• esp. in Javascript (React)
• but also in backends
• Developer Tooling
• Working Group for Spec

16. Example

17. Conference - App

18. Conference – App: Listing
{ onDay(day: Mi) {
id
title
speaker { name }
track { name }
slot {
start, time }
}}

19. Conference - Result
{[
{ id: "98a8ad", title: "Refactoring ..."
speaker: [{ name: "Oliver Gierke" }]
track: {name: "Modern Architecture"}
slot: {start: 9:00, time: 60}
},
...
]}

20. Conference – App: Details
{ talk(id:"98a8ad") {
id, title
speaker { name, pic }
track { name }
slot {
start, time, date}
abstract, text,
audience, level, req
}}

21. Conference - Result
{[{ id: "98a8ad", title: "Refactoring ..."
speaker: [{ name: "Oliver Gierke",
pic: "http://..." }]
track: {name: "Modern Architecture"}
slot: {start: 9:00, time: 60, date: ".."}
text: "", level: "Expert", req: "DDD..."
}
]}

22. Reuse Retrieved Data
{ talk(id: "Mi 1.1") {
id, title
speaker { name, pic }
track { name }
slot {
start, time, date}
abstract, text,
audience, level, req
}}

23. Conference - Schema
type Talk {
id: ID!
title: String!
abstract: String
speaker: [Person!]!
slot: Slot!
audience, level, ..
}
type Person {
email: ID!
name: String!
talks: [Talk]
}
type Slot {
day: Day
start: Time
}

24. Conference - Schema
type TalkMutations {
rate(id:ID!, rating:Int, comment:String)
: Talk
}
schema {
mutations: TalkMutations
}

25. Conference - Mutation
mutation rate(id:2342,rating:5,
comment:"Really useful") {
title
speaker {
name
}
}

26. Conference - Result
{
title: "Cloud Native Java",
speakers: [{
name: "Josh Long"
}]
}

27. GraphiQL Query Tool

28. OOP Demo

29. Takeaway - The Essence of GraphQL:
Strict, typed schema
enables
flexible, safe Queries

30. Goals

31. Goals
• Developer productivity
• Focus on Front-End needs
• Enable Tool Building
• Fast Validation
• Clear Communication

32. What issues wants GraphQL to solve?
• one shape of resource vs. many different needs
• custom shape of data query
• type safe and valid
• latency & roundtrips
• updates as commands, http verbs not expressive enough
• language for communication between teams
• front-end & back-end can develop independently
• better developer tooling

33. Design Principles

34. Design Principles
•Hierarchical
•Product Centric (front-end)
•Introspective
•Strong Typing
•Client‐specified queries

35. Design Principles
• a language used to query application servers that have
capabilities defined in this specification
• does not mandate a particular programming language
or storage system
• map capabilities to a uniform language, type system, and philosophy
• unified interface friendly to product development
and a powerful platform for tool‐building

36. Specification

37. What is GraphQL Spec ?
• Formal language specification for schema & operations
• Developed by Working Group
• at Facebook
• collaborates with community
• Published (regularly) after updates
• Reference Implementation (JavaScript)
http://facebook.github.io/graphql/ http://graphql.org/learn/

38. What is in the GraphQL Spec ?
• Schema
• Types
• Query Language
• Mutations
• Subscriptons
• Extensibility
• Parameters
• Expected behavior
• Fragments
• Results & Errors
• No prescribed transport
• Mostly HTTP (GET or POST)
http://facebook.github.io/graphql/ http://graphql.org/learn/

39. Specification
Example

40. github.com/sogko/graphql-schema-language-cheat-sheet

41. Types
• Object Types
• Unions
• Interfaces
• Input Typ
• Enums
• Scalar Types
• Built-In:
Int, Float, String, Boolean, ID
• Nullability
• Arrays
https://github.com/sogko/graphql-schema-language-cheat-sheet

42. Query
http://facebook.github.io/graphql/ http://graphql.org/learn/
schema {
query: QueryType
}
type QueryType {
talksOnDay(day:Day) [Talk] @cached
}

43. Mutation
http://facebook.github.io/graphql/ http://graphql.org/learn/
schema {
mutation: TalkUpdates
}
type TalkUpdates {
rate(talk:Talk, rating:Int) Talk
}

44. Mutation
http://facebook.github.io/graphql/ http://graphql.org/learn/
input type RatingInput {
talk: Talk
rating: Int
}
type TalkUpdates {
rate(rating:RatingInput) Talk
}

45. Subscriptions
type ConferenceSubscription {
talkUpdated(track: String!): TalkUpdate
}
schema {
subscription: ConferenceSubscription
}
https://www.apollographql.com/docs/graphql-subscriptions/subscriptions-to-schema.html

46. Subscriptions
subscription {
talkUpdated(track: "Moderne Architektur") {
id
title
speaker { name }
slot { start, duration }
}}
https://www.apollographql.com/docs/graphql-subscriptions/subscriptions-to-schema.html

47. Subscriptions
•Mutations trigger Domain Events
•explicit or implicit
•Domain Event triggers Subscription update
•Websocket or HTTP transport / PubSub
•Supported in Clients
https://dev-blog.apollodata.com/tutorial-graphql-subscriptions-server-side-e51c32dc2951

48. Directive
http://facebook.github.io/graphql/ http://graphql.org/learn/
type Talk {
speaker: [Person] @relation
(name:'PRESENTED',direction:OUT)
duration: Int @deprecated
}

49. Others
• (named) Fragments
• Union, Interfaces, Enum
• Params with defaults
• Variables
• Aliases
• Multiple Operations

50. Execution

51. Executing GraphQL Requests
1. parse (syntax)
2. validate (semantics)
3. execute
1. resolve fields
2. combine results
4. return result or errors
new concept
Field Resolver + Data Fetcher
possibly multiple operations per request

52. SQL
NOSQL
Static
REST
GraphQL
ServerGraphQL
Schema
FieldResolver+DataFetcher
Parse
Validate
Merge
Results
computed

53. Transport & Auth

54. GraphQL Transport
• Not prescribed
• Most often HTTP on /graphql
• POST or GET
• Hard to cache
• HTTP 200 with inline errors
• Monitoring / Tracing by middleware

55. GraphQL Auth
• In GraphQL server
• In Middleware before
• In Field resolver
• Use of directives @allowed(roles: [Admin])

56. SQL
NOSQL
Static
REST
computed
GraphQL
Server
Mobile Apps
SPA (React, Ang, Vue)
API Consumers
End Users
Any Language / Platform
Middle
ware
Cache
Aggregator
Cache
Aggregator
Cache
Aggregator

57. Development

58. GraphQL Development
1. Schema First – Agree on first iteration of schema
2. Register Schema
3. Implement Type Resolver
4. Fetch Data (static, db, api)
5. Implement Client App view with GraphQL client library
6. Iterate

59. Uses

60. GraphQL Uses
Larger Companies
• Consolidate sprawling APIs
• API domain language
• API Facades (Schema stitching)
• Wrap data sources & APIs
• Automatic API documentation
• API monitoring
• API evolution
Anyone (esp. Startups)
• Webapp development
• Mobile app development
• Quick Prototyping
• GraphQL as a service

61. DDD

62. GraphQL and Domain Driven Design

63. Users

65. Introspection

66. Introspection
{ __type(name:"Talk") {
name
fields {
name
description
}}}
• in every backend
• queryable via graphql
• for validation
• type completion
• visualization
• fetching Schema SDLhttps://github.com/graphql-cli/graphql-cli

67. Documentation
# Conference Sessions
type Talk {
# id, e.g. Mi 3.2
id: ID!
title: String!
abstract: String
# multiple speakers
speaker: [Person!]!
}
• auto-generated from schema
• comments as docs
• browseable in client
• helpful for type completion

68. GraphiQL

69. Voyager

70. Tools

71. GraphQL DBaaS – Graph.Cool
• playground
• backed by database
• automatic mutation & query generation
• automatic field parameters
• auth
• serverless functions
• resolvers
• graph.cool / neo4j-graphql

72. Apollo Launchpad

73. Apollo Engine

74. GraphQL Client Libraries
•apollo (js, android, ios)
•graphql.js
•relay-modern
•...

75. GraphQL DB-API / DBaaS
• Prisma / GraphCool
• Join-Monster
• PostGraphQL / PostGraphile
• Neo4j-GraphQL

76. Schema Stitching
GraphQL Join
Apollo Link
Gramps (IBM)

77. GraphQL Server Libraries (graphql-*)
• JavaScript
• Java
• Scala (Sangria)
• Ruby
• Python (Graphene)
• Go
• .Net
• PHP
• ...

78. GraphQL Community
• GraphQL Summit
• 2016,2017,2018
• GraphQL-Europe
• 2016, 2017
• GraphQL Slack
• 4500 users
• Meetups
• 65 groups
• 23000 members

79. 3Things I like about

80. Contract for a common
vocabulary

81. Flexible Querying

82. Extensibility

83. REST

84. RESTful API
• several resources, reachable via URI
• links between resources
• HTTP as protocol
• different representations / media-types, .e.g JSON

85. Philosophy & Guidelines
REST is software design on the scale of decades: every
detail is intended to promote software longevity and
independent evolution. Many of the constraints are
directly opposed to short-term efficiency.
- Roy Fielding
http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

86. Philosophy & Guidelines
I think most people just make the mistake that it should
be simple to design simple things. In reality, the effort
required to design something is inversely proportional
to the simplicity of the result. As architectural styles go,
REST is very simple.
- Roy Fielding
http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

87. New API Description Languages & Tools
• Not much tooling in first 5 years
• Web Service Description Language (WSDL)
• Web Application Description Language (WADL)
• Restful Service Description Language (RSDL)
• HATEOAS – Hypermedia As The Engine Of Application State
• Swagger
• RESTful API Modeling Language (RAML)

88. GraphQL – REST
Comparison

89. GraphQL REST
free operation names for queries &
mutations
HTTP Verbs
strong type safety none
operations are fields in schema Resources at URIs
model changes require schema +
query changes
no API change through model change
addtive, deprecation, monitoring versioning, tagged resources
allows introspection communicates links to operations
depending on transport, minimally uses web infrastructure
strong tooling some tooling, depending on API tool

90. REST Benefits
• Well understood and known
• HTTP Protocol incl. Verbs
• Web Standards
• Web Infrastructure (Caching, Auth)
• Isolated Resources
• Dynamic links / data in REST API change client behavior

91. REST Issues
• Most RESTful API are just HTTP APIs
• Effort for complex queries (n+1, latency)
• Overfetching, Underfetching
• Versioning

92. GraphQL Benefits
• Type Safety
• Schema = Contract
• No overfetching, only resolve requested fields
• Single Request
• Combining Queries / Reusing existing Results
• Good set of libraries
• Explicit Specification + Reference Implementation
• Active Community / Drivers / Tools

93. GraphQL Issues
• Still New / Adoption
• Filtering
• Aggregation
• Auth
• Move aggregation to server
• Caching in Server & Client
• Larger Request Sizes
• Can't change hierarchy structure

94. Ressources
1. graphql.org
2. howtographql.com
3. github.com/chentsulin/awesome-graphql
4. graph.cool
5. github.com/graphql-java
6. Artikel MH JS 4/2017 (github.com/jexp/javaspektrum-graphql-
demo)

95. Thank YOU
Questions?
@mesirii