At the CodeTalks conference 2017 in Hamburg, LeanIX presented their lessons learned for GraphQL, a new alternative for building REST APIs which was introduced by Facebook.

1. GraphQL
Lessons Learned
Bernd Schönbach, Patrick Surrey
LeanIX GmbH

2. Agenda
2
Introduction
• About us
• About LeanIX
• About GraphQL
Why GraphQL?
GraphiQL
API Design
GraphQL Client Design
Apollo
Mutations
N + 1 Select Issue
Exception Handling

3. About Us
3
Patrick Surrey Bernd Schönbach

4. About LeanIX
4

5. 5
• Shorter time to market
• Real-time big data insights
• Efficient scalability
• Exceptional user experience
• Consistent channels
• Integrated workflows
• …
More
• APIs
• Devices
• Sensors
IT Architectures are more important than ever before

6. LeanIX is the most comfortable solution – as SaaS
6
Available Integrations

7. 7
Industrials &
Manufacturing
Financial &
Insurance Consumer
Energy &
Materials Pharma
Travel
Logistics
Media
Telecoms
INTERNATIONAL
EXPANSION
Well-known brands of all industries trust in LeanIX

8. LeanIX is based on a modern Microservices Stack
8
Pathfinder
Postgres
Elasticsearch
ArangoDB
Pathfinder UI
Single Page App
•Angular (2)
•Typescript
Backend Services
•GraphQL or REST API
•oAuth2 /w JWT
•Swagger API Docs
•Event-Bus (Webhooks)
Resources
•No sharing across
services
•Deployment with
Docker
Web-
hooks
MTM Export
Image
s
Survey Metric
Postgres
Kafka
Postgres
Shibboleth
PhantomJS
Postgres
Elasticsearch
InfluxDB
“Platform Services”
GraphQL

9. About GraphQL
9

10. 10
“A query language for your API”
http://graphql.org/

11. 11
History
• 2012 native mobile client for News Feed
• Early 2015 announced publicly
(https://www.youtube.com/watch?v=9sc8Pyc51uU)
• Sep. 2015 officially open sourced
• Nov. 2016: Many more users

12. 12
Basic idea
Server
WHAT is
available
Client
WHICH data
is needed
1. Schema
2. Data requirements
Java, Node, Ruby,
PHP, Go, Scala,
.NET …
Simple HTTP-Client
http://graphql.org/code/

13. Why GraphQL?
13

14. Why GraphQL?
14
Application {
id
name
type
release
alias
description
Lifecycles {...}
Relations {
Successors
Predecessors
Business Capabilities
User Groups
[...]
}
[...]
}
Application {
id
name
type
release
alias
description
Lifecycles {...}
Relations {
Successors
Predecessors
Business Capabilities
User Groups
[...]
}
[...]
}

15. Why GraphQL?
15
Application {
id
name
type
release
alias
description
Lifecycles {...}
Relations {
Successors
Predecessors
Business Capabilities
User Groups
[...]
}
[...]
}
Application {
id
name
type
release
alias
description
Lifecycles {...}
Relations {
Successors
Predecessors
Business Capabilities
User Groups
[...]
}
[...]
}

16. Why GraphQL?
16
Application {
id
name
type
release
alias
description
Lifecycles {...}
Relations {
Successors
Predecessors
Business Capabilities
User Groups
[...]
}
[...]
}
Application {
id
name
type
release
alias
description
Lifecycles {...}
Relations {
Successors
Predecessors
Business Capabilities
User Groups
[...]
}
[...]
}
Application {
id
name
type
release
alias
description
Lifecycles {...}
Relations {
Successors
Predecessors
Business Capabilities
User Groups
[...]
}
[...]
}
Application {
id
name
type
release
alias
description
Lifecycles {...}
Relations {
Successors
Predecessors
Business Capabilities
User Groups
[...]
}
[...]
}

17. Why GraphQL?
17
Application {
id
name
type
release
alias
description
Lifecycles {...}
Relations {
Successors
Predecessors
Business Capabilities
User Groups
[...]
}
[...]
}
Application {
id
name
type
release
alias
description
Lifecycles {...}
Relations {
Successors
Predecessors
Business Capabilities
User Groups
[...]
}
[...]
}

18. Why GraphQL?
18
Application {
id
name
type
release
alias
description
Lifecycles {...}
Relations {
Successors
Predecessors
Business Capabilities
User Groups
[...]
}
[...]
}
query {
id name type release
alias description
...on Application {
lifecycles {}
relToSuccessor {}
relToPredecessor {}
relToBusinessCapability {}
relToUserGroups {}
[...]
}
}

19. Why GraphQL?
19
Application {
id
name
type
release
alias
description
Lifecycles {...}
Relations {
Successors
Predecessors
Business Capabilities
User Groups
[...]
}
[...]
}
query {
id name type release
alias description
}

20. Why GraphQL?
20
Application {
id
name
type
release
alias
description
Lifecycles {...}
Relations {
Successors
Predecessors
Business Capabilities
User Groups
[...]
}
[...]
}
Application {
id
name
type
release
alias
description
Lifecycles {...}
Relations {
Successors
Predecessors
Business Capabilities
User Groups
[...]
}
[...]
}
Application {
id
name
type
release
alias
description
Lifecycles {...}
Relations {
Successors
Predecessors
Business Capabilities
User Groups
[...]
}
[...]
}
query {
id name
}
query {
id name alias
}
query {
id name description
}

21. Why GraphQL?
21
Application {
id
name
type
release
alias
description
Lifecycles {...}
Relations {
Successors
Predecessors
Business Capabilities
User Groups
[...]
}
[...]
}
query {
id name
...on Application {
lifecycles {}
relToBusinessCapabilities {}
relToUserGroups {}
}
}

22. GRAPHIQL

23. GraphiQL –Interactive in-browser GraphQL IDE
23
Run queries
Integrated Explore API
See result

24. GraphiQL
24
• Available here: https://github.com/graphql/graphiql
• Great way to document and explore the API
• Very helpfull during devolpment, e.g. for quickly testing the API
à Get it up and running from day one!

25. API DESIGN

26. Connections – Inspired by Relay Framework
26
{
"id": "factsheet-123”,
"tags": [
{ "id": "tag-1", "label": "Tag 1" },
{ "id": "tag-2", "label": "Tag 2" },
{ "id": "tag-3", "label": "Tag 3" }
]
}
{
id
tags { id label }
}
Fact
Sheet
Tag
Tag
Tag

27. Connections
27
{
"id": "factsheet-123”,
"tags": {
"edges": [
{ "node": { "id": "tag-1", "label": "Tag 1" } },
{ "node": { "id": "tag-2", "label": "Tag 2" } },
{ "node": { "id": "tag-3", "label": "Tag 3" } }
]
}
}
{
id
tags {
edges {
node { id label }
}
}
}
Fact
Sheet
Tag
Tag
Tag

28. Connections - Advantages
28
{
id
tags {
totalCount
pageInfo { startCursor endCursor hasNextPage }
edges {
node { id label }
}
}
}

29. Connections - Advantages
29
{
id
tags {
permissions { create read update delete }
edges {
node { id label }
}
}
}

30. Connections – Lessons learned
30
• Makes the API more graph like
• Use the connection pattern right from the start
• Prevents breaking changes in API
• Use the same pattern throughout the API
• Clients can handle connections in the same way

31. API Design – No “dead ends”
31
{
id
tagId
}
{
id
tag { id label }
}

32. API Design – General lessons learned
32
• API design should be not too use case specific
• YAGNI („You aren‘t gonna need it“) is usually a good advice, but should
not be applied here
• GraphQL is advertised as „... gives clients the power to ask for exactly
what they need“ so do not artificially restrict the API

33. GRAPHQL CLIENT DESIGN

34. Doomed to fail ...
34
Lots of parameters
Nobody dares to touch this
Even more
generic

35. GraphQL client – Query building
35
No parameters
Simple! :-)
Helper to make requests

36. APOLLO

37. What about the Apollo Client?
37
• Apollo Client available here:
https://github.com/apollographql/apollo-client
• “A fully-featured, production ready caching GraphQL client for every
server or UI framework”
• Deep integration possible with React, Angular, iOS, Android, …

38. What about the Apollo Client?
38

39. So, what about it then?
39
• Did you use it?
• No, it was not available when we started …
• Would you use it?
• Perhaps - it offers some nice abstractions (queries can be restarted
for instance), but our own very simplistic approach works very well
at the moment

40. Mutations
40

41. Mutations
41
Mutation createApplication(name: “Application A“,
alias: „APP-A“) {
name
alias
}
GraphQL Suggests:

42. Mutations
42
Mutation createFactSheet(input: {
name: “Application A“, type: Application
}, patches: $patches) {
name
alias
}
Query:
{ patches: [
{op:“add“, path:“/alias“, value:“APP-A“}
]}
Variables:

43. N + 1 Select Issue
43

44. What is the N + 1 Select Issue?
44
Application application = appDAO.getApplication();
for(Successor successor: application.getSucessors()) {
System.out.println(“Successor:“ + successor.getName());
}
Application application = appDAO.getApplication();
for(Successor successor: application.getSucessors()) {
System.out.println(“Successor:“ + successor.getName());
}
SELECT * FROM application WHERE ...SELECT * FROM application WHERE ...
SELECT * FROM successor WHERE id = successor.id;
SELECT * FROM successor WHERE id = successor.id;
SELECT * FROM successor WHERE id = successor.id;
...
# Selects
1
N
+
SELECT * FROM successor WHERE id = successor.id;
SELECT * FROM successor WHERE id = successor.id;
SELECT * FROM successor WHERE id = successor.id;
...

45. Why do we have this issue with GraphQL?
45
Application {
id
name
type
release
alias
description
Lifecycles {...}
Relations {
Successors
Predecessors
Business Capabilities
User Groups
[...]
}
[...]
}

46. Why do we have this issue with GraphQL?
46
• Java Library uses Datafetcher
• Is a function to connect GraphQL to underlying DB
• Knows only his level

47. Why do we have this issue with GraphQL?
47
Application {
id
name
type
release
alias
description
Lifecycles {...}
Relations {
Successors
Predecessors
Business Capabilities
User Groups
[...]
}
[...]
}
id
name
type
release
alias
description
Lifecycles
Relations
id
name
type
release
alias
description
Lifecycles
Relations

48. Why do we have this issue with GraphQL?
48
• No context awareness
• No easy implementation due to „everything is a graph“
• Needs manual implementation to fix.

49. How To Solve This
49
• Prediction Library (enable context awareness)
• Batching
• Caching
• Facebooks solution is called relay

50. Exception Handling
50

51. Exception Handling
51
• Exceptions of Java GraphQL Library are useless
• “An error occurred“
• You need context information to show usefull exceptions
• We implemented our own handler for that

52. Conclusion
52

53. Conclusion
53
• Stop thinking in REST
• No dead ends
• GrahpiQL first
• GraphQL is not the solution for erverything

54. Breaking News
54

55. Breaking News
55

56. Breaking News
56
https://medium.com/@dwalsh.sdlr/using-graphql-why-facebook-now-owns-you-3182751028c9

57. Breaking News
57
https://code.facebook.com/posts/121714468491809/relicensing-the-graphql-specification/

58. Thank You

59. Questions?

60. Slides are available at:
https://de.slideshare.net/leanIX_net

61. Sources
• http://williamdurand.fr/2014/02/14/please-do-not-patch-like-an-idiot/
• http://graphql.org/
• https://github.com/graphql/graphiql
• https://www.leanix.net/de
• https://www.apollodata.com
• https://github.com/graphql-java/graphql-java
• https://angular.io/
• https://facebook.github.io/relay/