Slide 1

Slide 1 text

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”: [{...}, ...]}}

Slide 10

Slide 10 text

Documentation ● Creating Documentation ● Maintaining Documentation ● Fix Typo

Slide 11

Slide 11 text

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

Slide 12

Slide 12 text

Well-designed Query Language Fetch all with one query.

Slide 13

Slide 13 text

Well-designed Query Language Fetch only fields needed.

Slide 14

Slide 14 text

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

Slide 15

Slide 15 text

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

Slide 16

Slide 16 text

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

Slide 17

Slide 17 text

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

Slide 18

Slide 18 text

Try idobata.io/api

Slide 19

Slide 19 text

How to Write a GraphQL Server

Slide 20

Slide 20 text

Domain Models

Slide 21

Slide 21 text

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

Slide 22

Slide 22 text

The API for initial implementation Request Response

Slide 23

Slide 23 text

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

Slide 24

Slide 24 text

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

Slide 25

Slide 25 text

Defining a Schema

Slide 26

Slide 26 text

Defining a Type

Slide 27

Slide 27 text

It works!

Slide 28

Slide 28 text

Released API

Slide 29

Slide 29 text

HTTP Endpoint POST /api/graphql

Slide 30

Slide 30 text

No content

Slide 31

Slide 31 text

GraphiQL for Development Explore the API and the documentation

Slide 32

Slide 32 text

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

Slide 33

Slide 33 text

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

Slide 52

Slide 52 text

Thank You! Any questions?