Building a Web API with
GraphQL
2017/04/19 Tokyo Rubyist Meetup
https://flic.kr/p/hW3bX8
Slide 2
Slide 2 text
Hello
● Gentaro Terada (@hibariya)
● Works at ESM, Inc.
● A member of Idobata development team
● A college student (engineering)
● https://hibariya.org
Slide 3
Slide 3 text
Building a Web API with GraphQL
I’ll talk about:
● What is GraphQL
● How to Write a GraphQL Server
● Practical GraphQL Server
Slide 4
Slide 4 text
What is GraphQL
Slide 5
Slide 5 text
GraphQL: A query Language for API
Request Response
Slide 6
Slide 6 text
Difficulties w/ API Development
● Multiple Round Trips
● Over-fetching
● Dealing with Association
● Documentation
https://flic.kr/p/obcZW9 (cropped)
Slide 7
Slide 7 text
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
Slide 8
Slide 8 text
Over-fetching
A client needs just its name.
{“organization”: {
“name”: “Tokyo Rubyist Meetup”
“rooms”: [{..., “members”: { … }}, ...]
“members”: [{...}, ...]}}
Slide 9
Slide 9 text
Dealing with Association
What associations should be included???
{“organization”: {
“name”: “Tokyo Rubyist Meetup”
“rooms”: [{..., “members”: { … }}, ...]
“members”: [{...}, ...]}}
Mutations
For operations which have side-effects
● Creating/updating/deleting entities
● Marking messages as read
● Joining/Leaving chat rooms
● Sending mails
Slide 34
Slide 34 text
Defining a Mutation
mutation ≈ query + side-effects
Slide 35
Slide 35 text
Operation
Slide 36
Slide 36 text
Executing a Mutation
Slide 37
Slide 37 text
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
Slide 38
Slide 38 text
Practical GraphQL Server
Slide 39
Slide 39 text
GraphQL Relay Specification
Slide 40
Slide 40 text
Connection
● Represents one-to-many relationships
● Includes standardized pagination mechanism
Slide 41
Slide 41 text
Pagination w/ Position and Limit
Slide 42
Slide 42 text
Defining a Connection Field
Slide 43
Slide 43 text
Querying w/ Metadata
Slide 44
Slide 44 text
No content
Slide 45
Slide 45 text
Avoiding N+1 Query Problem
Slide 46
Slide 46 text
Eager Loading?
Message.includes(:room) won’t work:
● A client might not need the association (:room)
● Another client might need other associations
Slide 47
Slide 47 text
Avoiding N+1 Query w/ Batching
Defer loading with github.com/Shopify/graphql-batch
Slide 48
Slide 48 text
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
Slide 49
Slide 49 text
Timeout and Limit Depth/Complexity
Slide 50
Slide 50 text
Practical GraphQL Server
Summary:
● Connection is useful for pagination
● Use batch-loading to avoid N+1 query
● Protect overload with timeout and limiting query
Slide 51
Slide 51 text
Conclusion
● GraphQL solves common problems about Web API
● You can use it with Ruby
● There are common concerns and practical tips about
implementing servers