GraphQL - what is it and why you need it

This presentation was held at JavaBin's summer meetup at Teknologihuset in Oslo.

Parts of the Q/A session:
Q: How do you deal with adding/removing fields in GraphQL?
A: Adding is simple. Removing is not. Usual practice is to mark a field as deprecated and then remove it later on

Q: What are some challenges with performances?
A: No limits on query depths might affect performance, but you can cope with this by planning your database queries properly. Instrumentation that lets you know about slow queries (logging queries slower than a certain threshold to your ELK stack for instance) .

Q: Is there any library that lets you map your database model to GraphQL queries?
A: Not a library, but there is something called Prisma. See: https://www.prisma.io/ for a tool that autogenerates a GraphQL server based on your database model.

Q: What about caching? GraphQL is all POST. How do you handle caching?
A: Two-fold answer: Caching in the client is handled by the client of your choice. Apollo client has a read-through cache in it that will cache a lot of your data (can be turned off if necessary). Caching on the server can be implemented in your service/module layer.

Q: What is the most important tip you can give to developers that are new to GraphQL?
A: Focus on delivering value to your customer(s). GraphQL may potentially *not* be the answer to your pain points, so keep an eye out for that. However, all things considered, the most important part of implementing a GraphQL server is being really aware of the business domain and creating a model that maps more or less 1-1 to the business domain.

Q: How do you avoid breaking schemas between frontend and backend?
A: Feel free to pick your own solution. In my team, we currently don't have anything specific beyond code reviews. However, you can run linters that expose any schema breakage.

Transcript

1. GRAPHQL WHAT IS IT AND WHY YOU NEED IT
2. What is GraphQL?
3. What is it NOT?
4. It is NOT a graph database
5. It is NOT a library
6. It is NOT a javascript thing
7. It is NOT a facebook thing
8. What is GraphQL?
9. GraphQL is a spec
10. GraphQL has multiple implementations
11. A BRIEF HISTORY
12. 2012: Internal launch at Facebook A BRIEF HISTORY
13. 2015: First public release 2012: Internal launch at Facebook A BRIEF HISTORY
14. 2018: 
 10+ language implementations
 2015: First public release 2012: Internal launch at Facebook A BRIEF HISTORY
15. BUT FIRST
16. CAN’T WE JUST REST?
17. Arnab Datta
18. Arnab Datta GET people/1
 { “id": “1”, “name”: “Arnab Datta” }
19. Arnab Datta Title: Senior Consultant Project #1 Project #2 University of Oslo 1 Osloveien Age: 31 Email: arnab.datta@evry.com
20. Arnab Datta Title: Senior Consultant Project #1 Project #2 University of Oslo 1 Osloveien Age: 31 Email: arnab.datta@evry.com GET people/1 { “id": “1”, “name”: “Arnab Datta”, “email”: “arnab.datta@evry.com“, “university”: “1”, “address” : “1 Osloveien”, “projects”: [ “1”, “2”] } GET universities/1 { “id": “1”, “name”: “University of Oslo” } GET projects/1 { “id": “1”, “name”: “Project #1” } GET projects/2 { “id": “2”, “name”: “Project #2” }
21. Arnab Datta Title: Senior Consultant Project #1 Project #2 University of Oslo 1 Osloveien Age: 31 Email: arnab.datta@evry.com GET people/1 { “id": “1”, “name”: “Arnab Datta”, “email”: “arnab.datta@evry.com“, “university”: “1”, “address” : “1 Osloveien”, “projects”: [ “1”, “2”] } GET universities/1 { “id": “1”, “name”: “University of Oslo” } GET projects/1 { “id": “1”, “name”: “Project #1” } GET projects/2 { “id": “2”, “name”: “Project #2” }
22. Arnab Datta Title: Senior Consultant Project #1 Project #2 University of Oslo 1 Osloveien Age: 31 Email: arnab.datta@evry.com GET people/1 { “id": “1”, “name”: “Arnab Datta”, “email”: “arnab.datta@evry.com“, “university”: “1”, “address” : “1 Osloveien”, “projects”: [ “1”, “2”] } GET universities/1 { “id": “1”, “name”: “University of Oslo” } GET projects/1 { “id": “1”, “name”: “Project #1” } GET projects/2 { “id": “2”, “name”: “Project #2” }
23. Arnab Datta Title: Senior Consultant Project #1 Project #2 University of Oslo 1 Osloveien Age: 31 Email: arnab.datta@evry.com GET people/1 { “id": “1”, “name”: “Arnab Datta”, “email”: “arnab.datta@evry.com“, “university”: “1”, “address” : “1 Osloveien”, “projects”: [ “1”, “2”] } GET universities/1 { “id": “1”, “name”: “University of Oslo” } GET projects/1 { “id": “1”, “name”: “Project #1” } GET projects/2 { “id": “2”, “name”: “Project #2” }
24. That’s multiple requests for just one view, and things might (will) get worse as we get more data.
25. Arnab Datta GET people/1 { “id": “1”, “name”: “Arnab Datta”, “email”: “arnab.datta@evry.com”, “university”: “1”, “address” : “1 Osloveien”, “projects”: [ “1”, “2”] } Also: we are wasting bandwidth
26. HOW ABOUT CUSTOM ENDPOINTS?
27. Dev1: What was the name of that endpoint to get info on a person? /People? Dev2: Yes
28. A few moments later…
29. Dev1: What was the name of that endpoint to get info on a person? /People? Dev2: Yes Dev1: What if I want to get a list of their friends Dev2: /PeopleWithFriends . Remember to supply the ID of the person whose friends you’re looking for.
30. A few moments later…
31. Dev1: What was the name of that endpoint to get info on a person? /People? Dev2: Yes Dev1: What if I want to get a list of their friends Dev2: /PeopleWithFriends . Remember to supply the ID of the person whose friends you’re looking for. Dev1: I keep getting a 400 error Dev2: Let me see… Oh the ID needs to be a string, so you need to put it in quotes.
32. Much much later…
33. Dev1: What was the name of that endpoint to get info on a person? /People? Dev2: Yes Dev1: What if I want to get a list of their friends Dev2: /PeopleWithFriends . Remember to supply the ID of the person whose friends you’re looking for. Dev1: I keep getting a 400 error Dev2: Let me see… Oh the ID needs to be a string, so you need to put it in quotes. Dev1: What if I want to get a list of the friends of their friends? Dev2: … Make a custom endpoint friendsOfFriendsForPerson?
35. Some pain points
36. • The gap between documentation and actual implementation drives me insane on a daily basis, closely followed by poorly chosen endpoint names and inconsistency of both data input and output. Some pain points
37. • Lack of example code and live test environments readily available. Language specific SDKs are nice to have. • The gap between documentation and actual implementation drives me insane on a daily basis, closely followed by poorly chosen endpoint names and inconsistency of both data input and output. Some pain points
38. • I hate having to transform data just to fit every single endpoint. I am lazy • Lack of example code and live test environments readily available. Language specific SDKs are nice to have. • The gap between documentation and actual implementation drives me insane on a daily basis, closely followed by poorly chosen endpoint names and inconsistency of both data input and output. Some pain points
39. GraphQL
40. Describe your data GraphQL
41. type Person { name: String email: String age: String friends: [Person!]! } type Query { people(id: ID) : Person } Describe your data GraphQL
42. type Person { name: String email: String age: String friends: [Person!]! } type Query { people(id: ID) : Person } Describe your data Ask for what you want GraphQL
43. people(id: “1”) { name friends {
 name } } type Person { name: String email: String age: String friends: [Person!]! } type Query { people(id: ID) : Person } Describe your data Ask for what you want GraphQL
44. { “Person”: { “name”: “Tom Thomson” “friends” : [ { “name”: “John Doe” } ] } } people(id: “1”) { name friends {
 name } } type Person { name: String email: String age: String friends: [Person!]! } type Query { people(id: ID) : Person } Describe your data Ask for what you want GraphQL
45. { “Person”: { “name”: “Tom Thomson” “friends” : [ { “name”: “John Doe” } ] } } people(id: “1”) { name friends {
 name } } type Person { name: String email: String age: String friends: [Person!]! } type Query { people(id: ID) : Person } Describe your data Ask for what you want GraphQL Get only what you asked for
46. SO WHAT’S THE BIG DEAL?
47. Big wins (non-exhaustive list)
48. • Strong Typing and a domain- specific model that clients and servers agree upon. There can be a 1-1 mapping between your data and your API responses. Big wins (non-exhaustive list)
49. • Frontend developers get exactly the shape they want, resulting in less friction while developing. • Strong Typing and a domain- specific model that clients and servers agree upon. There can be a 1-1 mapping between your data and your API responses. Big wins (non-exhaustive list)
50. • Backend developers can be as strict as they want about the data they expose, how they expose it and how they validate input. In other words, more fine-grained control • Frontend developers get exactly the shape they want, resulting in less friction while developing. • Strong Typing and a domain- specific model that clients and servers agree upon. There can be a 1-1 mapping between your data and your API responses. Big wins (non-exhaustive list)
51. LETS SEE THIS IN ACTION
52. SO WHAT’S THE CATCH?
53. Some drawbacks (non-exhaustive list)
54. • You need to think more about your data model than before. “Just give me a JSON” is not an option anymore. Some drawbacks (non-exhaustive list)
55. • Be (slightly) restrictive when it comes to what queries you allow. Avoid the 1+N problem where you do N queries for each root object because it has N instances of a subfield. • You need to think more about your data model than before. “Just give me a JSON” is not an option anymore. Some drawbacks (non-exhaustive list)
56. • Caching is harder because GraphQL is all about flexibility of your queries. • Be (slightly) restrictive when it comes to what queries you allow. Avoid the 1+N problem where you do N queries for each root object because it has N instances of a subfield. • You need to think more about your data model than before. “Just give me a JSON” is not an option anymore. Some drawbacks (non-exhaustive list)
57. DIFFERENCES REST GraphQL
58. •Under/overfetching DIFFERENCES REST GraphQL •No under/overfetching
59. •Under/overfetching •Needs multiple requests DIFFERENCES REST GraphQL •No under/overfetching •Can get everything in one request
60. •Under/overfetching •Needs multiple requests •Documentation must be kept up-to-date DIFFERENCES REST GraphQL •No under/overfetching •Can get everything in one request •Self-documenting API that can be experimented with
61. •Under/overfetching •Needs multiple requests •Documentation must be kept up-to-date •Input is validated at runtime DIFFERENCES REST GraphQL •No under/overfetching •Can get everything in one request •Self-documenting API that can be experimented with •Strongly typed input validation that can be stopped pre-execution
62. •Under/overfetching •Needs multiple requests •Documentation must be kept up-to-date •Input is validated at runtime •Custom endpoints DIFFERENCES REST GraphQL •No under/overfetching •Can get everything in one request •Self-documenting API that can be experimented with •Strongly typed input validation that can be stopped pre-execution •Strongly typed output •Existing models can be recycled/reused
63. THANK YOU