GraphQL for fun & profit

At Redbubble, we've been building an API for our new mobile app. While initially choosing a RESTful JSON style API, we quickly hit limits with this and moved to GraphQL, a new-ish query language developed at Facebook. This talk will cover the highlights of GraphQL, why you should care, as well as deep diving into Sangria, a GraphQL framework for Scala.

Transcript

1. GRAPHQL FOR FUN & Tom Adams, @tomjadams
 Director of Engineering, Redbubble API Days, 201702
4. WHY? $ curl -X GET http://api.products/v1/products val products: List[Product]
5. { "data": { "products": [{ "product_id": "2081256-US-t-shirt", "title": "no Christmas!", "product_url": "http://rb.com/people/akwel/works/2081256-no-christmas", "artist": { "username": "akwel", "avatar": "http://ih0.redbubble.net/avatar.40844.100x100.jpg", "profile_url": "http://www.redbubble.com/people/akwel", "location": "London, United Kingdom" }, "images": ["http://ih.rb.net/ra,unisex_tshirt,x1350,f8f8f8.jpg"], "price": { "currency": "AUD", "amount": "31.88" } }] } }
6. { "data": { "products": [{ "product_id": "2081256-US-t-shirt", "title": "no Christmas!", "product_url": "http://rb.com/people/akwel/works/2081256-no-christmas", "artist": { "username": "akwel", "avatar": "http://ih0.redbubble.net/avatar.40844.100x100.jpg", "profile_url": "http://www.redbubble.com/people/akwel", "location": "London, United Kingdom" }, "images": ["http://ih.rb.net/ra,unisex_tshirt,x1350,f8f8f8.jpg"], "price": { "currency": "AUD", "amount": "31.88" } }] } }
7. { "data": { "products": [{ "product_id": "2081256-US-t-shirt", "title": "no Christmas!", "product_url": "http://rb.com/people/akwel/works/2081256-no-christmas", "artist": { "username": "akwel", "avatar": "http://ih0.redbubble.net/avatar.40844.100x100.jpg", "profile_url": "http://www.redbubble.com/people/akwel", "location": "London, United Kingdom" }, "images": ["http://ih.rb.net/ra,unisex_tshirt,x1350,f8f8f8.jpg"], "price": { "currency": "AUD", "amount": "31.88" } }] } }
8. { "data": { "products": [{ "product_id": "2081256-US-t-shirt", "title": "no Christmas!", "product_url": "http://rb.com/people/akwel/works/2081256-no-christmas", "artist": { "username": "akwel", "avatar": "http://ih0.redbubble.net/avatar.40844.100x100.jpg", "profile_url": "http://www.redbubble.com/people/akwel", "location": "London, United Kingdom" }, "images": ["http://ih.rb.net/ra,unisex_tshirt,x1350,f8f8f8.jpg"], "price": { "currency": "AUD", "amount": "31.88" } }] } }
9. API IS FIXED!
10. Source: https://medium.com/@ottovw/rest-api-downfalls-and-dawn-of-graphql-dd00991a0eb8#.9davlqfzf
11. PROBLEMS WITH REST • Over & under fetching • Multiple calls to get data • Weak typing • Standards • Documentation • Tooling • API is fixed (coupled to server development)
12. REST SOLUTIONS /joe.smith/friends?fields=id,name,picture ?fields=title,media:group(media:thumbnail)
13. GraphQL
14. GRAPHQL • GraphQL inverses the client/server relationship • Rather than a server giving a client all the things • A client asks for what it wants • This leads to solutions for (most of) the problems we’ve identified
15. HISTORY • Developed by Facebook • Used internally at FB since 2012 • Open sourced July 2015 • 15+ programming languages • Specification: https://facebook.github.io/graphql
16. DESIGN THEMES • Hierarchical (fields) • Product (frontend)-centric • Client-specified queries • Structured, arbitrary code • Application-layer protocol (no transport) • Strongly-typed • Backwards compatible^ • Introspective Source: https://facebook.github.io/react/blog/2015/05/01/graphql-introduction.html
17. WHAT IS GRAPHQL? • A simple type system • A schema • Your domain, expressed using GraphQL types • A query language to query (your) schema
18. WHAT IT ISN’T • A runtime to execute the query (e.g. Sangria) • An encoding mechanism (e.g. JSON) • A transport (e.g. HTTP) • Client side bindings, e.g. model generators • Tools, e.g. GraphiQL, other introspection tools • A server • A graph database query language
20. { product { url } }
21. { "data": { "product": { "url": "http://ih.rb.net/ra,...,f8f8f8.jpg" } } }
22. { product { url } } field document
23. query findProduct { product(id:"1") { url } }
24. query findProduct { product(id:"1") { url } } operation argument
25. query findProduct($id: Int!) { product(id: $id) { url } }
26. { "id": 1 }
27. mutation addProductMutation { addProduct( input:{ id: 2, url: "http://ih.rb.net/2.jpg" } ) { url } }
28. mutation addProductMutation { addProduct( input:{ id: 2, url: "http://ih.rb.net/2.jpg" } ) { url } } argument (input type) fields
29. QUERIES VS. MUTATIONS • Let's you split the reads from the writes • But, just different namespaces • No actual difference, you can mutate in queries • Mutations are "inconsistent", in that no rules are applied to how to pass inputs • Single vs. multiple parameters
30. $ curl -i -X POST --data '{ "query":"query findProduct($id: Int!) { product(id: $id) { url } }", "variables":{"id":1}, "operationName":"findProduct" }' "http://host.com/graphql" HTTP/1.1 200 OK Content-Type: application/json {"data":{"product":{"url":"http://ih.rb.net/ra,...,f8f8f8.jpg"}}}
32. TYPESYSTEM • Scalar • Lists • Object • Non-null (Option) • Enum • Union • Interface • Input • Custom scalar type
33. SCHEMA type Product { url: String }
34. ADVANCED • Directives allow modification of query execution • Conditionals, etc. • Field aliases • Fetch multiple fields in a single query • Fragments • Reuse common fields/structures • Inline fragments • Union types; discriminate based on runtime type
36. KILLER FEATURES • Represent the domain • e.g. “Redbubble domain model” • Types • Introspection & documentation • Ease of exposing new data via the API • Guarantees on request & response format
37. RESOURCES • Learn • http://graphql.org/learn/ • https://github.com/mugli/learning-graphql • Spec • https://facebook.github.io/graphql/ • Sangria • http://sangria-graphql.org
38. 38 QUESTIONS?