Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Building a Web API with GraphQL

Building a Web API with GraphQL

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

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

Hibariya Hi

April 19, 2017
Tweet

More Decks by Hibariya Hi

Other Decks in Technology

Transcript

  1. Building a Web API with
    GraphQL
    2017/04/19 Tokyo Rubyist Meetup
    https://flic.kr/p/hW3bX8

    View full-size slide

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

    View full-size 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 full-size slide

  4. What is GraphQL

    View full-size slide

  5. GraphQL: A query Language for API
    Request Response

    View full-size slide

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

    View full-size 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 full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size 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 full-size slide

  18. Try idobata.io/api

    View full-size slide

  19. How to Write a GraphQL Server

    View full-size slide

  20. Domain Models

    View full-size slide

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

    View full-size slide

  22. The API for initial implementation
    Request Response

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  25. Defining a Schema

    View full-size slide

  26. Defining a Type

    View full-size slide

  27. Released API

    View full-size slide

  28. HTTP Endpoint
    POST /api/graphql

    View full-size slide

  29. GraphiQL for Development
    Explore the API and the documentation

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  33. Executing a Mutation

    View full-size slide

  34. 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 full-size slide

  35. Practical GraphQL Server

    View full-size slide

  36. GraphQL Relay Specification

    View full-size slide

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

    View full-size slide

  38. Pagination w/ Position and Limit

    View full-size slide

  39. Defining a Connection Field

    View full-size slide

  40. Querying w/ Metadata

    View full-size slide

  41. Avoiding N+1 Query Problem

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  44. 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 full-size slide

  45. Timeout and Limit Depth/Complexity

    View full-size slide

  46. 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 full-size slide

  47. 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 full-size slide

  48. Thank You!
    Any questions?

    View full-size slide