From REST to GraphQL

My talk, given at ElixirConf MX in Mexico City on November 18th, 2017. This 30 minute session highlighted basic features of GraphQL that are not present and/or have differing implementations across different flavors of REST. (Also touches on the features/use of Absinthe, the GraphQL toolkit for Elixir.)

Transcript

1. FROM REST TO GRAPHQL Bruce Williams
3. CARGOSENSE
6. http://absinthe-graphql.org The GraphQL Toolkit for Elixir
7. 2 years ~18k SLOC ~50 Contributors ~50 Releases ~1k Slack Members ~ 1.5k GH ★ 1 Book
10. GRAPHQL WHAT IS ?
11. GRAPH QL
12. GRAPH QUERY LANGUAGE
13. 2012-2015: Internal project (focused on mobile app APIs) Sep 2015: Open sourced spec working draft, Relay framework (based on React) Facebook Other client/server implementations followed, along with spec additions.
14. Your data is already a graph. Now, just describe it with a schema.
15. The schema defines the relationship between data types.
16. User queries are trees They want to retrieve…
17. query { allPosts(limit: 10) { title publishedAt author { name } body comments { author { name } body } } }
18. {“data”: { “allPosts”: [ { “title”: “Using Absinthe”, “publishedAt”: “2017-11-17T00:20:00Z”, “author”: {“name”: “…”}, “body”: “…”, “comments” [ {“author”: {“name”: }, “body”: “…”}, … ] }, … ] }
19. starting at a special root type…
20. and walking the relationships (fields)…
21. resolving the value for each…
22. then traversing to their fields..
27. building a tree of results—JSON, just like a REST request.
28. HOW DOES ABSINTHE HELP?
29. object :user do field :name, non_null(:string) field :posts, list_of(:post), resolve: … end object :post do field :title, non_null(:string) field :author, non_null(:author), resolve: … field :comments, list_of(:comment), resolve: … end … Macros!
30. I’ve been using GraphQL quite heavily for the last 8 months, primarily with JavaScript and I’ve found it to be a fairly tedious experience. I tried out an Elixir GraphQL library that's heavily based on macros and was almost immediately more productive—despite not even knowing the language. “ andrewingram, HN, 2016-05-08
31. plug Absinthe.Plug, schema: MyAppWeb.Schema forward “/graphql”, Absinthe.Plug, schema: MyAppWeb.Schema Plug + Phoenix! or…
32. forward “/graphiql”, Absinthe.Plug.GraphiQL, schema: MyAppWeb.Schema, interface: :playground API UIs
34. :datetime :naive_datetime :date :time :decimal Custom Types! build your own…
35. Query Subscribed Effect Response None Mutation Subscription Data Connection Data Later Data None None Data Modified triggers Manual push
36. absinthe-graphql / absinthe absinthe-graphql / absinthe_plug absinthe-graphql / absinthe_ecto absinthe-graphql / absinthe_phoenix Client Support absinthe-graphql / dataloader absinthe-graphql / absinthe-socket absinthe-graphql / absinthe_relay
37. WHY TAKE THE JUMP?
38. The future is here and it is GraphQL. RIP REST. “ @ryanbigg, 2017-11-15
39. REST is an inadequately shallow API standard for the needs of the modern web. “ Me, right now A few examples…
40. URL REST: Read the documentation, if there is documentation. Hopefully it’s up to date. forward “/graphql”, Absinthe.Plug, schema: MyAppWeb.Schema http: //example.com/graphql
41. “Resources” REST: Read the documentation, if there is documentation. Hopefully it’s up to date. query { __schema { types { name # kind, description, fields, etc } } }
42. METHOD REST: GET, POST, PUT, and DELETE. You can always use POST. You can use GET for query operations.
43. websockets REST: Undefined. While connection methods differ across GraphQL server implementations, you’re always passing GraphQL across them.
44. Data Scope REST: Server defines the scope, may provide params (structure commonly undefined), and data is returned in… any structure. Clients declare the data that they want. The server returns the data (that it deems safe to) in the same structure
45. Errors REST: Undefined, beyond HTTP Response Code ranges. May return JSON or free-form text error messages. {“errors”: [ {“message”: “”, “locations”: […], …}, … ]}
46. Partial Data { “data”: { “categories”: [{“name”: “News”}, …], “user”: null }, “errors”: [ {“message”: “You are not authorized”, “path”: [“user”], …}, … ] } query { categories { name } user(id: “abc123”) { email } } REST: Undefined. Rarely done.
47. Batching REST: Undefined; best path is usually to create a batch resource, and manually interact with it. { user1: user(id: “abc123”) { avatar(size: LARGE) { url } } user2: user(id: “abc321”) { avatar(size: LARGE) { url } } }
48. Validation REST: Undefined. Do-it-yourself. All input is validated against the schema. If validation fails, no execution occurs and the errors are immediately returned.
49. Scalars REST: Undefined. Do-it-yourself. String, ID, Float, Int, and others. You can create your own reusable scalar types if you define a way to parse and serialize it.
50. Reusability REST: Undefined. URL templating? Maybe? query Chat($userId: ID!, $size: AvatarSize!) { user(id: $userId) { … Avatar } } fragment Avatar on User { avatar(size: $size) { url } }
51. Aggregation REST: Undefined. Do it yourself. Field data can come from any data source. Database, external service, etc, and can be subject to data batching.
52. Bandwidth REST: Undefined. Filtering params, custom API namespaces, etc. Because clients can query with a language, they can ask for as little or as much data as they want. This is especially good for low-bandwidth mobile.
53. Notation REST: Undefined. Server controls style of notation. query { allPosts { … } } query { all_posts { … } } or
54. versioning REST: Undefined. Common approach is separate URL namespace. object :user do field :name, non_null(:string) field :display_name, :string do deprecate “Use `name` instead” end end Or use separate schemas.
55. EASE INTO IT REST + GraphQL REST using GraphQL for data (same app) GraphQL using REST (aggregating) GraphQL Absinthe.run/3
56. BOOK RELEASED (IN BETA) ElixirConf_MX http://bit.ly/2x34Q7F http://absinthe-graphql.org Links to GitHub, Slack, Twitter, etc: 25% Discount (this weekend only) with code: