GraphQL @ Shopify

1. G R APHQL S H O P IF Y
2. MA RC- ANDRE GIRO UX @__xuorig__ MONTREA L, C ANADA
4. G RAPH QL CORE TEAM
5. Goal: Make it easy for any team to build their own schemas
6. Goal: Make it easy for mobile developers to extend the schemas
7. Defining the Schema(s)
8. gem 'graphql' ❤
9. ShopType = ObjectType.define do name "Shop" description "An awesome shop!" field :name, types.String, "The shops's name” # `!` marks this field as non-null: field :currency, !types.Int # Returns a list of `ProductType`s field :products, types[PersonType] end
10. GraphModel / GraphApi
11. GraphQL gem GraphModel GraphApi
12. module GraphApi class Shop < GraphApi::ObjectType # Types are declared using symbols or type class field :name, :string # Explicit null kwarg to define non-null fields field :currency, :string, null: false field :products, [Product] end end
13. I can’t believe it’s not butter ActiveRecord!
14. module GraphApi class ProductVariant < GraphApi::ObjectType belongs_to :product, Product end end
15. module GraphApi class Product < GraphApi::ObjectType cache_has_many :variants, [ProductVariant] end end
16. module GraphApi class Product < GraphApi::ObjectType paginated :variants, ProductVariant end end
17. query { shop { products { image { url } } } }
18. query { shop { products { image { url } } } }
19. query { shop { products { image { url } } } } SELECT `shops`.* FROM `shops` WHERE `shops`.`id` = 1
20. query { shop { products { image { url } } } } SELECT `products`.* FROM `products` AND `products`.`shop_id` = 1
21. query { shop { products { image { url } } } } SELECT `product_images`.* FROM `product_images` WHERE `product_images`.`product_id` = 1 SELECT `product_images`.* FROM `product_images` WHERE `product_images`.`product_id` = 2 SELECT `product_images`.* FROM `product_images` WHERE `product_images`.`product_id` = 3
22. Products Image Image Image product1.image product3.image product2.image
23. Batching
24. https://github.com/Shopify/graphql-batch
25. loader = GraphModel::AssociationLoader.for(record.class, :image) loader.load(record) => #<GraphQL::Batch::Promise @callbacks=[], @state=:pending> Return a Promise
26. With Batching Products Image Image Image loader.load(1) loader.load(2) loader.load(3) => #<Promise> => #<Promise> => #<Promise>
27. class AssociationLoader < GraphQL::Batch::Loader def load(record) # => Cache and return a Promise end def perform(records) # Prefetch the associations and fulfill all promises! @model.prefetch_associations(@association_name, records) records.each { |record| fulfill(record, read_association(record)) } end end Defining a Loader
28. Promise.rb + Custom Executor
29. module GraphApi class Product < GraphApi::ObjectType field :image, ProductImage, preload: :image end end The API
30. module GraphApi class Product < GraphApi::ObjectType field :image, ProductImage, preload: :image end end The API
31. prefetch(obj, arguments, context).then do resolve(object, arguments, context) end Wrap resolve with promise
32. query { shop { products { image { url } } } } With Batching
33. query { shop { products { image { url } } } } SELECT `shops`.* FROM `shops` WHERE `shops`.`id` = 1
34. query { shop { products { image { url } } } } SELECT `products`.* FROM `products` AND `products`.`shop_id` = 1
35. query { shop { products { image { url } } } } SELECT `product_images`.* FROM `product_images` WHERE `product_images`.`product_id` IN (1, 2, 3)
36. query { shop { products { image { url } } } } SELECT `product_images`.* FROM `product_images` WHERE `product_images`.`product_id` IN (1, 2, 3)
37. Authorization / Authentication
38. module GraphApi class Order < GraphApi::ObjectType required_access(:orders) field :email, :string end end Type Access
39. module GraphApi class Order < GraphApi::ObjectType required_access(:orders) field :email, :string end end Type Access
40. module GraphApi class Order < GraphApi::ObjectType required_access(:orders, write: true) field :email, :string end end Type Access
41. module GraphApi class Order < GraphApi::ObjectType required_access(:orders) do |order| order.visible? end field :email, :string end end Type Access
42. context = { access: GraphApi::AccessControl.new(@access_token, @user) } AccessControl
43. Evil Clients
44. class Query def result Timeout.timeout(@timeout) { @query.result } rescue Timeout::Error { "errors" => [{ "message" => "Timeout" }] } end end Timeouts
45. class Query def result TimeThrottle.for(key, options) { @query.result } rescue TimeThrottle { "errors" => [{ "message" => "Throttled" }] } end end Throttling
46. Developer Experience
47. Checked-In IDL
48. Checked-In IDL
49. Protecting the Schema
50. Protecting the Schema
51. Protecting the Schema
52. Protecting the Schema
53. Conventions • Mutation actions are suffixed productCreate, not createProduct • Mutations return a `userErrors` field on errors • Support Relay spec (deletedId, newEdge, clientMutationId)
54. Conventions
55. Instrumentation
56. Deprecated Field Usage
57. Mobile Clients
58. Overview • Background • GraphQL Code Generator • Query Builders • Response Classes • Caching and Data Consistency
59. Mobile Shopify App • Rebuilt to provide full Shopify Admin • Fast on slow networks by reducing response sizes (REST -> GraphQL) Since Sept. 27
60. React-Native Experiment • ❤ GraphQL • ❤ Components • Quick to build, hard to polish • Switched to using native Android and iOS APIs • Need Java and Swift GraphQL clients
61. GraphQL Client Goals • Simplicity • Avoid unnecessary complexity • Quick to implement • Easy to understand • Productive mobile developer • Embrace static type system • IDE Integration (Android Studio & Xcode) • Build for long term • Components to decouple large codebase • Reduce schema evolution friction
62. GraphQL Schema The Killer Feature
63. Generate code from the schema script/update_schema Query Builders Classes Response Classes Schema
64. Query Builders
65. Swift Query Builder ApiSchema.buildQuery() { $0 .product(id: productId) { $0 .id() .title() .images(first: 1) { $0 .id() .src() } } } { product(id: "gid://shopify/Product/42") { id title images(first: 1) { id src } } } (Pretty Printed)
66. Java Query Builder APISchema.query(q -> q .product(productId, p -> p .id() .title() .images(1, img -> img .id() .src() ) ) ) • Requires java 8 lambda expressions: • Retrolambda backports to java 5-7 • New Jack Android toolchain { product(id: "gid://shopify/Product/42") { id title images(first: 1) { id src } } } (Pretty Printed)
67. Simple Query Composition func loadProduct() { let query := ApiSchema.buildQuery { $0 .product(id: productId, self.productDetailQuery) .shop(self.shopDetailQuery) } … } func productDetailQuery(_ product: ApiSchema.ProductQuery) { product .id() .title() …
68. Inline Fragments on Type ApiSchema.buildQuery { $0 .event(id: eventId) { $0 .message() .onCommentEvent { $0 .author() } } } { event(id: “gid://shopify/Event/42") { __typename id message ... on CommentEvent { author } } } (Pretty Printed)
69. Type-Safety and IDE Integration
70. Query Builders - Summary • Simplicity • No GraphQL variables, named fragments or directives • No IDE plugin required • Productive mobile developer • Type-safe • IDE features just work • Build for long term • Can declare data dependancies close to their use • script/update_schema to adapt to schema changes (e.g. deprecations)
71. Response Classes
72. Response objects guard let response = response.product else { logger.error("tried to view product details for deleted product") return } variants = product.variants.edges.map { $0.node } • Validates and deserializes fields based on their type in constructor • Field methods have appropriate return types • Leverages language type system, including swift optional types • Runtime error for accessing unqueried field • Replace model layer
73. Custom Scalars GraphQLGenerator::Swift.new(schema, nest_under: 'ApiSchema', custom_scalars: [ GraphQLGenerator::Swift::Scalar.new( type_name: 'Money', swift_type: 'NSDecimalNumber', deserialize_expr: ->(expr) { "NSDecimalNumber(string: #{expr}, locale: GraphQL.posixLocale)" }, serialize_expr: ->(expr) { "#{expr}.description(withLocale: GraphQL.posixLocale)" } ) ] ).save(output_directory)
74. Unknown Value/Type switch variant.inventoryPolicy { case .deny: // … case .unknownValue // generated enum value // handle values added in the future } // no default to handle all known cases // type check on GraphQL interface if let comment = event as? ApiSchema.CommentEvent { appendMessage(comment.message, author: comment.author) } else { // use interface fields for other/unknown object types appendMessage(comment.message) }
75. Response Classes - Summary • Simplicity • Replace hand written model layer • Productive mobile developer • Use field methods without coercion • Type system imposes constraints (e.g. enums, optionals) • IDE features work • Build for long term • Unknown types/values leave room for schema evolution • Server-side computed fields avoid inaccuracies as business logic changes
76. Caching and Data Consistency
77. Response Caching • Response cache, keyed by query string, persisted to disk • Optimistically render using cached response, but request still sent extension ProductDetailsViewController: Relayable { func handleRelayQuery( query: ApiSchema.QueryRootQuery, response: ApiSchema.QueryRoot?, error: GraphQueryError?, cached: Bool) { session.relayContainer.queryGraph(query: query, relayable: self)
78. Active Queries • List of active query stored in memory to render data changes • Weak reference to cleanup active queries after their view is freed extension ProductDetailsViewController: Relayable { func handleRelayQuery( query: ApiSchema.QueryRootQuery, response: ApiSchema.QueryRoot?, error: GraphQueryError?, cached: Bool) { session.relayContainer.queryGraph(query: query, relayable: self)
79. Mutations • Mutations apply to all active queries • Find nodes in all active queries that match a node in the payload by id: • Deep merge fields from payload node on active query node • Call handleRelayQuery to update view for active query session.relayContainer.mutateGraph(mutationQuery: mutation) { … } extension ProductDetailsViewController: Relayable { func handleRelayQuery( query: ApiSchema.QueryRootQuery, response: ApiSchema.QueryRoot?, error: GraphQueryError?, cached: Bool) {
80. Optimistic Updates • Optimistic update actions apply to all matching nodes in active queries • Rollback optimistically updated active queries from response cache before applying updates from mutation response let optimisticUpdate = RelayAction.Destroy(product) self.session.relayContainer.mutateGraph( mutationQuery: mutation, updates: [optimisticUpdate]) { (mutation, error) in APISchema.Order optimisticUpdate = new APISchema.Order(orderId()) .setClosed(true) .setClosedAt(SimpleRelativeDateUtil.now().getTimeInMillis());
81. Caching & Data Consistency - Summary • Simplicity • Cache whole responses • Productive mobile developer • Type checked optimistic updates • Build for long term • Data consistency without coupling
82. Follow our work https://engineering.shopify.com