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 との比較、そして実際にアプリケーションを構築した事例について共有します。

E39aeab4407ea02102f75584618549a4?s=128

Hibariya Hi

April 19, 2017
Tweet

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

  30. None
  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

  44. None
  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?