GraphQL @ Shopify

Transcript

1. G R APHQL S H O P IF Y
   

   View Slide

2. MA RC- ANDRE GIRO UX
   @__xuorig__
   MONTREA L, C ANADA
   

   View Slide

3. View Slide

4. G RAPH QL CORE TEAM
   

   View Slide

5. Goal: Make it easy for any team to build their own
   schemas
   

   View Slide

6. Goal: Make it easy for mobile developers to extend the
   schemas
   

   View Slide

7. Defining the Schema(s)
   

   View Slide

8. gem 'graphql' ❤
   

   View Slide

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
   

   View Slide

10. GraphModel / GraphApi
    

    View Slide

11. GraphQL gem
    GraphModel
    GraphApi
    

    View Slide

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
    

    View Slide

13. I can’t believe it’s not butter ActiveRecord!
    

    View Slide

14. module GraphApi
    class ProductVariant < GraphApi::ObjectType
    belongs_to :product, Product
    end
    end
    

    View Slide

15. module GraphApi
    class Product < GraphApi::ObjectType
    cache_has_many :variants, [ProductVariant]
    end
    end
    

    View Slide

16. module GraphApi
    class Product < GraphApi::ObjectType
    paginated :variants, ProductVariant
    end
    end
    

    View Slide

17. query {
    shop {
    products {
    image {
    url
    }
    }
    }
    }
    

    View Slide

18. query {
    shop {
    products {
    image {
    url
    }
    }
    }
    }
    

    View Slide

19. query {
    shop {
    products {
    image {
    url
    }
    }
    }
    }
    SELECT `shops`.* FROM `shops` WHERE
    `shops`.`id` = 1
    

    View Slide

20. query {
    shop {
    products {
    image {
    url
    }
    }
    }
    }
    SELECT `products`.* FROM `products` AND
    `products`.`shop_id` = 1
    

    View Slide

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
    

    View Slide

22. Products
    Image Image Image
    product1.image product3.image
    product2.image
    

    View Slide

23. Batching
    

    View Slide

24. https://github.com/Shopify/graphql-batch
    

    View Slide

25. loader = GraphModel::AssociationLoader.for(record.class, :image)
    loader.load(record)
    => #
    Return a Promise
    

    View Slide

26. With Batching
    Products
    Image Image Image
    loader.load(1) loader.load(2) loader.load(3)
    => # => # => #
    

    View Slide

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
    

    View Slide

28. Promise.rb + Custom Executor
    

    View Slide

29. module GraphApi
    class Product < GraphApi::ObjectType
    field :image, ProductImage, preload: :image
    end
    end
    The API
    

    View Slide

30. module GraphApi
    class Product < GraphApi::ObjectType
    field :image, ProductImage, preload: :image
    end
    end
    The API
    

    View Slide

31. prefetch(obj, arguments, context).then do
    resolve(object, arguments, context)
    end
    Wrap resolve with promise
    

    View Slide

32. query {
    shop {
    products {
    image {
    url
    }
    }
    }
    }
    With Batching
    

    View Slide

33. query {
    shop {
    products {
    image {
    url
    }
    }
    }
    }
    SELECT `shops`.* FROM `shops` WHERE
    `shops`.`id` = 1
    

    View Slide

34. query {
    shop {
    products {
    image {
    url
    }
    }
    }
    }
    SELECT `products`.* FROM `products` AND
    `products`.`shop_id` = 1
    

    View Slide

35. query {
    shop {
    products {
    image {
    url
    }
    }
    }
    }
    SELECT `product_images`.* FROM
    `product_images` WHERE
    `product_images`.`product_id` IN (1, 2, 3)
    

    View Slide

36. query {
    shop {
    products {
    image {
    url
    }
    }
    }
    }
    SELECT `product_images`.* FROM
    `product_images` WHERE
    `product_images`.`product_id` IN (1, 2, 3)
    

    View Slide

37. Authorization / Authentication
    

    View Slide

38. module GraphApi
    class Order < GraphApi::ObjectType
    required_access(:orders)
    field :email, :string
    end
    end
    Type Access
    

    View Slide

39. module GraphApi
    class Order < GraphApi::ObjectType
    required_access(:orders)
    field :email, :string
    end
    end
    Type Access
    

    View Slide

40. module GraphApi
    class Order < GraphApi::ObjectType
    required_access(:orders, write: true)
    field :email, :string
    end
    end
    Type Access
    

    View Slide

41. module GraphApi
    class Order < GraphApi::ObjectType
    required_access(:orders) do |order|
    order.visible?
    end
    field :email, :string
    end
    end
    Type Access
    

    View Slide

42. context = {
    access: GraphApi::AccessControl.new(@access_token, @user)
    }
    AccessControl
    

    View Slide

43. Evil Clients
    

    View Slide

44. class Query
    def result
    Timeout.timeout(@timeout) { @query.result }
    rescue Timeout::Error
    { "errors" => [{ "message" => "Timeout" }] }
    end
    end
    Timeouts
    

    View Slide

45. class Query
    def result
    TimeThrottle.for(key, options) { @query.result }
    rescue TimeThrottle
    { "errors" => [{ "message" => "Throttled" }] }
    end
    end
    Throttling
    

    View Slide

46. Developer Experience
    

    View Slide

47. Checked-In IDL
    

    View Slide

48. Checked-In IDL
    

    View Slide

49. Protecting the Schema
    

    View Slide

50. Protecting the Schema
    

    View Slide

51. Protecting the Schema
    

    View Slide

52. Protecting the Schema
    

    View Slide

53. Conventions
    • Mutation actions are suffixed productCreate, not createProduct
    • Mutations return a `userErrors` field on errors
    • Support Relay spec (deletedId, newEdge, clientMutationId)
    

    View Slide

54. Conventions
    

    View Slide

55. Instrumentation
    

    View Slide

56. Deprecated Field Usage
    

    View Slide

57. Mobile Clients
    

    View Slide

58. Overview
    • Background
    • GraphQL Code Generator
    • Query Builders
    • Response Classes
    • Caching and Data Consistency
    

    View Slide

59. Mobile Shopify App
    • Rebuilt to provide full Shopify Admin
    • Fast on slow networks by reducing response sizes (REST -> GraphQL)
    Since Sept. 27
    

    View Slide

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
    

    View Slide

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
    

    View Slide

62. GraphQL Schema
    The Killer Feature
    

    View Slide

63. Generate code from the schema
    script/update_schema
    Query
    Builders
    Classes
    Response
    Classes
    Schema
    

    View Slide

64. Query Builders
    

    View Slide

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)
    

    View Slide

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)
    

    View Slide

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()
    …
    

    View Slide

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)
    

    View Slide

69. Type-Safety and IDE Integration
    

    View Slide

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)
    

    View Slide

71. Response Classes
    

    View Slide

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
    

    View Slide

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)
    

    View Slide

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)
    }
    

    View Slide

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
    

    View Slide

76. Caching and Data Consistency
    

    View Slide

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)
    

    View Slide

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)
    

    View Slide

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)
    {
    

    View Slide

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());
    

    View Slide

81. Caching & Data Consistency - Summary
    • Simplicity
    • Cache whole responses
    • Productive mobile developer
    • Type checked optimistic updates
    • Build for long term
    • Data consistency without coupling
    

    View Slide

82. Follow our work
    https://engineering.shopify.com
    

    View Slide