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
   

   View Slide

2. Hello
   ● Gentaro Terada (@hibariya)
   ● Works at ESM, Inc.
   ● A member of Idobata development team
   ● A college student (engineering)
   ● https://hibariya.org
   

   View Slide

3. Building a Web API with GraphQL
   I’ll talk about:
   ● What is GraphQL
   ● How to Write a GraphQL Server
   ● Practical GraphQL Server
   

   View Slide

4. What is GraphQL
   

   View Slide

5. GraphQL: A query Language for API
   Request Response
   

   View Slide

6. Difficulties w/ API Development
   ● Multiple Round Trips
   ● Over-fetching
   ● Dealing with Association
   ● Documentation
   https://flic.kr/p/obcZW9 (cropped)
   

   View Slide

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
   

   View Slide

8. Over-fetching
   A client needs just its name.
   {“organization”: {
   “name”: “Tokyo Rubyist Meetup”
   “rooms”: [{..., “members”: { … }}, ...]
   “members”: [{...}, ...]}}
   

   View Slide

9. Dealing with Association
   What associations should be included???
   {“organization”: {
   “name”: “Tokyo Rubyist Meetup”
   “rooms”: [{..., “members”: { … }}, ...]
   “members”: [{...}, ...]}}
   

   View Slide

10. Documentation
    ● Creating Documentation
    ● Maintaining Documentation
    ● Fix Typo
    

    View Slide

11. What is Good in GraphQL?
    ● Well-designed Query Language
    ● Schema
    ● Introspection System
    

    View Slide

12. Well-designed Query Language
    Fetch all with one query.
    

    View Slide

13. Well-designed Query Language
    Fetch only fields needed.
    

    View Slide

14. Schema
    Describes the service
    ● Type Definitions
    ● Data Structure
    ● Operations
    ● Restrictions
    ● Human-readable Descriptions
    

    View Slide

15. Introspection System
    Powerful tools and up-to-date documentation.
    

    View Slide

16. Differences from REST
    ● Single Endpoint
    ● Mutations for Destructive Operations
    ● Data Types and Structures
    

    View Slide

17. What is GraphQL
    Summary:
    ● GraphQL is a query language for API
    ● API development is difficult
    ● GraphQL is one of the best solutions
    

    View Slide

18. Try idobata.io/api
    

    View Slide

19. How to Write a GraphQL Server
    

    View Slide

20. Domain Models
    

    View Slide

21. Domain Models
    Guy (User) →
    Organization→
    Room→
    ← Message
    ↑ (Room view)
    

    View Slide

22. The API for initial implementation
    Request Response
    

    View Slide

23. Defining a Schema
    Describes the service
    ● Type Definitions
    ● Data Structure
    ● Operations
    ● Restrictions
    ● Human-readable Descriptions
    

    View Slide

24. Defining a Schema w/ Ruby
    github.com/rmosolgo/graphql-ruby
    

    View Slide

25. Defining a Schema
    

    View Slide

26. Defining a Type
    

    View Slide

27. It works!
    

    View Slide

28. Released API
    

    View Slide

29. HTTP Endpoint
    POST /api/graphql
    

    View Slide

30. View Slide

31. GraphiQL for Development
    Explore the API and the documentation
    

    View Slide

32. GraphiQL Rails::Engine
    github.com/rmosolgo/graphiql-rails
    

    View Slide

33. Mutations
    For operations which have side-effects
    ● Creating/updating/deleting entities
    ● Marking messages as read
    ● Joining/Leaving chat rooms
    ● Sending mails
    

    View Slide

34. Defining a Mutation
    mutation ≈ query + side-effects
    

    View Slide

35. Operation
    

    View Slide

36. Executing a Mutation
    

    View Slide

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
    

    View Slide

38. Practical GraphQL Server
    

    View Slide

39. GraphQL Relay Specification
    

    View Slide

40. Connection
    ● Represents one-to-many relationships
    ● Includes standardized pagination mechanism
    

    View Slide

41. Pagination w/ Position and Limit
    

    View Slide

42. Defining a Connection Field
    

    View Slide

43. Querying w/ Metadata
    

    View Slide

44. View Slide

45. Avoiding N+1 Query Problem
    

    View Slide

46. Eager Loading?
    Message.includes(:room) won’t work:
    ● A client might not need the association (:room)
    ● Another client might need other associations
    

    View Slide

47. Avoiding N+1 Query w/ Batching
    Defer loading with github.com/Shopify/graphql-batch
    

    View Slide

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
    

    View Slide

49. Timeout and Limit Depth/Complexity
    

    View Slide

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
    

    View Slide

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
    

    View Slide

52. Thank You!
    Any questions?
    

    View Slide