GraphQL in an Age of REST

Slide 1

Slide 1 text

GraphQL in an Age of REST Yos Riady yos.io goo.gl/prnEnz

Slide 2

Slide 2 text

A step-by-step walkthrough of building a GraphQL server Drawbacks to building Web APIs with REST Background REST GraphQL Code Next Steps An overview of GraphQL, with examples Further learning, future improvements, and conclusion The current state of Web APIs

Slide 3

Slide 3 text

An API is a user interface for developers - so put some effort into making it pleasant.

Slide 4

Slide 4 text

Background

Slide 5

Slide 5 text

Web APIs are eating the world

Slide 6

Slide 6 text

No content

Slide 7

Slide 7 text

Slide 8

Slide 8 text

Introduction to REST Separate your API to logical resources. Map actions to HTTP methods and URIs. ● GET /posts - Retrieves a list of posts ● GET /posts/12 - Retrieves a specific post ● POST /posts - Creates a new post ● PUT /posts/12 - Updates post #12 ● PATCH /posts/12 - Partially updates post #12 ● DELETE /posts/12 - Deletes post #12

Slide 9

Slide 9 text

No content

Slide 10

Slide 10 text

Posts

Slide 11

Slide 11 text

Posts Users Comments

Slide 12

Slide 12 text

A HackerNews-like Data Model author_id post_id body Comment author_id title url published_at votes Post name joined_at User POST /posts GET /posts/1 PUT /posts/1 DELETE /posts/1 GET /posts/1/author GET /posts/1/comments POST /users GET /users/1 PUT /users/1 DELETE /users/1 GET /users/1/posts GET /users/1/comments POST /comments GET /comments/1 PUT /comments/1 DELETE /comments/1

Slide 13

Slide 13 text

No content

Slide 14

Slide 14 text

No content

Slide 15

Slide 15 text

Let’s try using our API

Slide 16

Slide 16 text

No content

Slide 17

Slide 17 text

Retrieve a list of posts GET /posts { “posts”: [{ “id”: 1 “author_id”: 101, “title”: “GraphQL in an Age of REST”, “body”: “lorem ipsum”, “votes”: 342, “published_at”: “2016-10-11T16:53:28+00:00” }, ... ] }

Slide 18

Slide 18 text

Retrieve a list of posts GET /posts GET /users/101 { “user”: { “id”: 101 “name”: “yosriady”, “joined_at”: “2015-10-11T16:53:28+00:00” } }

Slide 19

Slide 19 text

Retrieve a list of posts GET /posts GET /users/101 GET /users/102 GET /users/103 ...

Slide 20

Slide 20 text

Problem: Multiple roundtrips

Slide 21

Slide 21 text

No content

Slide 22

Slide 22 text

No content

Slide 23

Slide 23 text

There are many cases where an API consumer needs to load data related to the resource being requested. GET /posts/1?embed=author.name { “post”: { “id”: 1 ... “author”: { “name”: “yosriady” } } } Solution: Autoload related resources

Slide 24

Slide 24 text

Another Problem: Over-fetching of data APIs often return a huge JSON object with many fields, even when we only use a handful. Solution: Clients should be able to specify the fields they only need. GET /posts/1?fields=title,link,published_at

Slide 25

Slide 25 text

Solution: Custom Endpoints Your API DB 1 DB 2 v1 v2 v1 v2 v3

Slide 26

Slide 26 text

Problem: Custom Endpoints /posts_with_everything_i_need /posts_with_everything_i_need_with_author_v2 /posts_with_everything_for_samsung_smart_tv /tightly_coupled_endpoint_for_a_specific_client Whoa! We end up with a lot of endpoints.

Slide 27

Slide 27 text

An API is only as good as its documentation.

Slide 28

Slide 28 text

Problem: How will users learn our API? ● Users ○ API consumers ○ Developers from other teams ○ New hires ● Documentation must cover: ○ What resources does the API manage? ○ What actions can I perform? ○ Endpoint parameters ■ Required ■ Optional ■ Attribute Types

Slide 29

Slide 29 text

● API Specification languages ○ OpenAPI (fka Swagger) ○ API Blueprint ○ JSON Schema ● Third-party services ● Benefits ○ Auto-generated documentation ○ Auto-generated Server stubs ○ Auto-generated Client code Solution: API Specifications

Slide 30

Slide 30 text

Summary: Drawbacks of REST APIs need to be documented well enough for consumers to be able to discover and learn it on their own. Documentation /tightly_coupled_endpoi nt_for_a_specific_clien t REST APIs are rigid. Over-fetching. Custom endpoints lead to bloat. Custom endpoints GET /posts/1 GET /comments/1001 GET /comments/1002 Getting the data you need can require multiple REST calls away. Multiple round trips

Slide 31

Slide 31 text

Slide 32

Slide 32 text

GraphQL

Slide 33

Slide 33 text

Introduction to GraphQL ● A declarative (1) query language, (2) type system, and (3) runtime for client applications to fetch and mutate data. ● Devised to solve some of the problems with REST ○ Originally used by the Facebook Product team ● Data store independent ● Language and platform independent

Slide 34

Slide 34 text

It’s Graphs All the Way Down

Slide 35

Slide 35 text

It’s Graphs All the Way Down

Slide 36

Slide 36 text

Queries have the same shape as its result Here is a (1) GraphQL Query and its response: { post(id: 1) { title url author { name } } } { "post": { "title": "GraphQL in an Age of REST", "url”: “http://yos.io”, “author”: { “name”: “yosriady” } } }

Slide 37

Slide 37 text

Power to the client instead of the server The client specifies what data it needs, and the server does only what is necessary to return that data.

Slide 38

Slide 38 text

/graphql

Slide 39

Slide 39 text

No content

Slide 40

Slide 40 text

goo.gl/nV3WJE goo.gl/nV3WJE

Slide 41

Slide 41 text

No content

Slide 42

Slide 42 text

Great API documentation drives adoption.

Slide 43

Slide 43 text

The (2) Type System makes all of this possible

Slide 44

Slide 44 text

Schema Language type Post { title: String! author: User! comments:[Comment]! } type Query { post(id: Int): Post posts: Post }

Slide 45

Slide 45 text

Types ● Scalar types ○ Boolean ○ Int ○ Float ○ String ○ Custom types i.e. Date ● Enums ● Lists ● Interfaces ● Unions

Slide 46

Slide 46 text

Summary: Benefits of GraphQL API playground Client-side validation Self-documenting Introspective Adapts to different requirements for different clients Client-specified Query from multiple data sources in a single network request. Single round trip

Slide 47

Slide 47 text

Slide 48

Slide 48 text

Building a GraphQL Server in Node.js

Slide 49

Slide 49 text

Preamble A GraphQL service is created by providing (a) the schema and (b) resolver functions. ● We’ll use ○ Node.js + Express ○ express-graphql

Slide 50

Slide 50 text

Preamble ● Bindings are available for all major languages ○ Javascript ○ Ruby ○ PHP ○ Python ○ Java ○ C/C++ ○ Go ○ Scala ○ .NET ○ Elixir ○ Haskell ○ SQL ○ Lua ○ Elm ○ Clojure

Slide 51

Slide 51 text

yos-graphql.surge.sh

Slide 52

Slide 52 text

A GraphQL Schema Definition const User = new GraphQLObjectType({ name: 'User', fields: () => ({ id: { type: GraphQLInt }, name: { type: GraphQLString } }) });

Slide 53

Slide 53 text

Creates links between data sources and GraphQL fields posts(id){ return request(`https://api.blog.io/posts/${id}`); } posts(id){ return sql.raw('SELECT * FROM posts WHERE id = %s',id); } posts(id){ return DB.Posts.getById(id); } GraphQL Resolvers

Slide 54

Slide 54 text

Slide 55

Slide 55 text

● Give GraphQL a try, especially if ○ Your product is an API ○ You have many clients with flexible requirements ● Features not covered in this talk ○ Aliases, ○ Fragments, ○ Variables, ○ Directives, etc. ● Best practices still emerging In Closing

Slide 56

Slide 56 text

meetup.com/API-Craft-Singapore

Slide 57

Slide 57 text

Thanks Yos Riady yos.io

Slide 58

Slide 58 text

Questions? Yos Riady yos.io

Slide 59

Slide 59 text

Appendix 0: Differences from REST ● A single endpoint `/graphql` ● Only HTTP verbs GET and POST are used ○ GET for queries ○ POST for mutations ● Support for other transport layers ○ MQTT for IOT domains

Slide 60

Slide 60 text

Appendix 1: Versioning “We encourage GraphQL endpoints to take an add-only approach to schema evolution over time instead of changing existing fields.” GraphQL takes a strong opinion on avoiding versioning by providing the tools for the continuous evolution of a GraphQL schema.

Slide 61

Slide 61 text

Appendix 2: Cons of GraphQL ● Initial investment may not make sense where ○ APIs are internal -> use RPC ○ API changes are rare (APIs are stable) ● Performance ○ Compared to RPC