Building a Web API with GraphQL

https://trbmeetup.doorkeeper.jp/events/59184

現実の Web API は複雑なものになりがちで設計の悩みは尽きません。GraphQL は、API を提供するうえでありがちないくつかの問題に対するひとつの解決策を提供します。GraphQL は API のためのクエリ言語です。シンプルな文法でクライアントの要求を自然に、 また明確に記述できます。この発表では GraphQL とは何か、REST との比較、そして実際にアプリケーションを構築した事例について共有します。

Transcript

1. Building a Web API with GraphQL 2017/04/19 Tokyo Rubyist Meetup https://flic.kr/p/hW3bX8
2. Hello • Gentaro Terada (@hibariya) • Works at ESM, Inc. • A member of Idobata development team • A college student (engineering) • https://hibariya.org
3. Building a Web API with GraphQL I’ll talk about: • What is GraphQL • How to Write a GraphQL Server • Practical GraphQL Server
4. What is GraphQL
5. GraphQL: A query Language for API Request Response
6. Difficulties w/ API Development • Multiple Round Trips • Over-fetching • Dealing with Association • Documentation https://flic.kr/p/obcZW9 (cropped)
7. Multiple Round Trips Organization => Rooms => Members • GET /organizations/:id • GET /organizations/:org_id/rooms • GET /organizations/:org_id/rooms/:id/members Requests: Organizations Count * 2 + Rooms Count
8. Over-fetching A client needs just its name. {“organization”: { “name”: “Tokyo Rubyist Meetup” “rooms”: [{..., “members”: { … }}, ...] “members”: [{...}, ...]}}
9. Dealing with Association What associations should be included??? {“organization”: { “name”: “Tokyo Rubyist Meetup” “rooms”: [{..., “members”: { … }}, ...] “members”: [{...}, ...]}}
10. Documentation • Creating Documentation • Maintaining Documentation • Fix Typo
11. What is Good in GraphQL? • Well-designed Query Language • Schema • Introspection System
12. Well-designed Query Language Fetch all with one query.
13. Well-designed Query Language Fetch only fields needed.
14. Schema Describes the service • Type Definitions • Data Structure • Operations • Restrictions • Human-readable Descriptions
15. Introspection System Powerful tools and up-to-date documentation.
16. Differences from REST • Single Endpoint • Mutations for Destructive Operations • Data Types and Structures
17. What is GraphQL Summary: • GraphQL is a query language for API • API development is difficult • GraphQL is one of the best solutions
18. Try idobata.io/api
19. How to Write a GraphQL Server
20. Domain Models
21. Domain Models Guy (User) → Organization→ Room→ ← Message ↑ (Room view)
22. The API for initial implementation Request Response
23. Defining a Schema Describes the service • Type Definitions • Data Structure • Operations • Restrictions • Human-readable Descriptions
24. Defining a Schema w/ Ruby github.com/rmosolgo/graphql-ruby
25. Defining a Schema
26. Defining a Type
27. It works!
28. Released API
29. HTTP Endpoint POST /api/graphql
31. GraphiQL for Development Explore the API and the documentation
32. GraphiQL Rails::Engine github.com/rmosolgo/graphiql-rails
33. Mutations For operations which have side-effects • Creating/updating/deleting entities • Marking messages as read • Joining/Leaving chat rooms • Sending mails
34. Defining a Mutation mutation ≈ query + side-effects
35. Operation
36. Executing a Mutation
37. How to Write a GraphQL Server Summary: • A schema can be defined w/ Ruby • Various protocols can be used • Mutations for operations which have side-effects
38. Practical GraphQL Server
39. GraphQL Relay Specification
40. Connection • Represents one-to-many relationships • Includes standardized pagination mechanism
41. Pagination w/ Position and Limit
42. Defining a Connection Field
43. Querying w/ Metadata
45. Avoiding N+1 Query Problem
46. Eager Loading? Message.includes(:room) won’t work: • A client might not need the association (:room) • Another client might need other associations
47. Avoiding N+1 Query w/ Batching Defer loading with github.com/Shopify/graphql-batch
48. Overload Protection • Too big/complex queries • Queries which causes too many communication with DB • Queries which take too long time https://flic.kr/p/aosdja
49. Timeout and Limit Depth/Complexity
50. Practical GraphQL Server Summary: • Connection is useful for pagination • Use batch-loading to avoid N+1 query • Protect overload with timeout and limiting query
51. Conclusion • GraphQL solves common problems about Web API • You can use it with Ruby • There are common concerns and practical tips about implementing servers
52. Thank You! Any questions?