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