GraphQL - A query language to empower your API consumers (NDC Sydney 2017)

Slide 1

Slide 1 text

@robdcrowley | robdcrowley GraphQL A query language to empower your API consumers

Slide 2

Slide 2 text

Goals for the session -Explore the motivation behind GraphQL and the category of problems it helps to solve. -Take a tour of GraphQL’s features and see it in action. -Investigate how to effectively leverage GraphQL in your delivery process. -Most of all sufficiently motivate you to continue to learn GraphQL after leaving this conference.

Slide 3

Slide 3 text

The shift to microservices, cloud native and rich web apps have made it challenging to deliver compelling API experiences

Slide 4

Slide 4 text

No content

Slide 5

Slide 5 text

Image Service Cross Sell Service Product Service Product Service Product Service Review Service Price Service Inventory Service Promotions Service Other Sellers Service Price Service Image Service Inventory Service Order Service Image Service Price Service

Slide 6

Slide 6 text

Cross Sell Component Header Component Product Image Component Product Review Component Product Price Component Product Inventory Component Product Purchase Component Alternate Sellers Component Product Details Component Offers Component Product Header Component

Slide 7

Slide 7 text

How can we efficiently deliver the data to the client?

Slide 8

Slide 8 text

A naïve approach Microservice Microservice Microservice Microservice Component Potentially high latency connection Component Component Component

Slide 9

Slide 9 text

Leveraging an API Gateway to reduce latency Microservice Microservice Microservice Microservice API Gateway Wait, we support more than one customer experience channel. How to handle these? Component Component Component Component

Slide 10

Slide 10 text

Introducing Backends for Frontends (BFFs) Microservice Microservice Microservice Microservice Mobile BFF Desktop BFF Wearables BFF What about the different data requirements between versions? V4, V5… On page reload V1, V2…

Slide 11

Slide 11 text

Retrieve exactly the data you require in a single round trip to the server

Slide 12

Slide 12 text

GraphQL as the translation layer Microservice Relational DB Graph DB Web Service GraphQL API Retrieve exactly the data every version of each channel experience requires in one round trip. optimised { data }

Slide 13

Slide 13 text

Source code available at https://github.com/robcrowley/graphql-demo

Slide 14

Slide 14 text

Our Example Domain Album Artist Label User Album Review compose submit favourite released on refers to 1 * * 1 1 * * 1 1 * artistId: int name: string albumId: int title: string labelId: int name: string founded: int userId: int name: string reviewId: int albumId: int review: string rating: int

Slide 15

Slide 15 text

Demo time: Just show me how it works already

Slide 16

Slide 16 text

Hey, just what are you trying to pull here!? Couldn’t we already do this with REST? Absolutely, but GraphQL makes it trivial and ensures a consistent interface.

Slide 17

Slide 17 text

GraphQL Core Concepts

Slide 18

Slide 18 text

Type System Execution Engine Anatomy of GraphQL Query Language

Slide 19

Slide 19 text

“Reliability problems largely occur at module boundaries, and most result from inconsistencies in both sides expectations” - Bertrand Meyer

Slide 20

Slide 20 text

type Artist { id: ID! name: String! aliases: [String] albums: [Album] }

Slide 21

Slide 21 text

let queryArtist = (_, {id}, {dao}) => { // arbitrary code to retrieve artist return dao.getArtist(id); } let artistName = artist => { return artist.name; }

Slide 22

Slide 22 text

root query { artist(id: “5”) { name albums { title label { name } } } } Label Producer Album User Artist Review

Slide 23

Slide 23 text

root query { artist(id: “5”) { name albums { } } } Label Producer Album User Artist Review

Slide 24

Slide 24 text

root Label Producer Album User Artist Review query { artist(id: “5”) { name albums { title label { } } } }

Slide 25

Slide 25 text

root Label Producer Album User Artist Review query { artist(id: “5”) { name albums { title label { name } } } }

Slide 26

Slide 26 text

Capabilities exposed as schema Requirements expressed as query GraphQL focusses on accessing data exposed by the graph This is a fundamental difference to REST which is concerned with modelling resources and state transitions. Clients Single /graphql endpoint *

Slide 27

Slide 27 text

GraphQL Operations -Query -> Read ( 1 : 1 ) -Mutation -> Write ( 1 : 1 ) -Subscription -> Observe Event ( 1 : 0..* )

Slide 28

Slide 28 text

-The second killer feature of GraphQL -Enables ‘reflection’ type queries on fields, types and schema -Extremely powerful for tooling support - Autocomplete (as seen in Graphiql) - Code generation - Documentation Introspection

Slide 29

Slide 29 text

Efficiency -Avoid overfetching and underfetching (particularly across the slow portion of the network to the client). -Reduced data handling complexity in the client. -Simpler extension model for backend API developers.

Slide 30

Slide 30 text

GraphQL is not tied to JavaScript. Server implementations exist for many languages. http://graphql.org/code

Slide 31

Slide 31 text

GraphQL is protocol agnostic. So long as the protocol supports exchanging character data you’re set.

Slide 32

Slide 32 text

GraphQL is not about binary data streams

Slide 33

Slide 33 text

“Every time time you change a version identifier, you’re potentially orphaning clients who ‘speak’ that language.” - Mark Nottingham

Slide 34

Slide 34 text

In place of versioning prefer an extension model to enable graceful evolution of the API contract

Slide 35

Slide 35 text

The @deprecated directive provides an elegant mechanism to facilitate this in GraphQL

Slide 36

Slide 36 text

GraphQL is not a shortcut to great API design. Solid modelling skills are still table stakes. (sorry, not sorry)

Slide 37

Slide 37 text

Think in Graphs* Avoid creating fields that should be types

Slide 38

Slide 38 text

Getting the most out of GraphQL

Slide 39

Slide 39 text

The schema solves one part of the API documentation challenge, it does not solve it completely

Slide 40

Slide 40 text

graphdoc + schema = professional static API documentation

Slide 41

Slide 41 text

Do not roll your own GraphQL client

Slide 42

Slide 42 text

Decide whether you will support Relay early https://facebook.github.io/relay

Slide 43

Slide 43 text

Naming is difficult and as such is a problem suited to API governance

Slide 44

Slide 44 text

is / can / has prefix for Boolean fields plural nouns for collections

Slide 45

Slide 45 text

Strive for field and type names that mirror the language of the business domain

Slide 46

Slide 46 text

“There are only two hard things in Computer Science: cache invalidation and naming things.” - Phil Karlton

Slide 47

Slide 47 text

GraphQL requires a different approach to caching

Slide 48

Slide 48 text

Caching Approaches for RESTful APIs Client Side Caching Server Side Caching HTTP offers rich caching functionality via caching headers: Cache-Control, ETag, Expires, Pragma & Vary.

Slide 49

Slide 49 text

Caching Approaches for RESTful APIs Client Side Caching Server Side Caching Intermediate Caching Proxy HTTP offers rich caching functionality via caching headers: Cache-Control, ETag, Expires, Pragma & Vary.

Slide 50

Slide 50 text

Caching Approaches for GraphQL APIs Client Side Caching Server Side Caching Intermediate Caching Proxy GraphQL does not play nice with the rest of the web, as it treats HTTP as a dump pipe. As such we need to rely on server and client caching.

Slide 51

Slide 51 text

Server Caching - Utilise a dedicated cache layer to minimize traffic downstream. - DataLoader implementations assist with per request batching and caching.

Slide 52

Slide 52 text

Client Caching - GraphQL clients such as Apollo or Relay help massively in this regard. - Hierarchical responses are flattened to create normalized caches where each record is stored exactly once. - Clients can leverage this cache to generate network efficient queries. query: { album (id: “1”): { name: “Endtroducing…" artist: { name: “DJ Shadow" } } } Map { 1: Map { name: “Endtroducing…”, author: Link(2), }, 2: Map { name: ‘DJ Shadow' }, }; Hierarchical Normalized

Slide 53

Slide 53 text

Inter API Communication - Inter API calls are easily supported in REST APIs based of the media type semantics. - In fact, Hypermedia is the under- pinning architectural style of the web. GET /artistsapi/artist/1 HTTP/1.1 ContentType: application/vnd.hal+json { “_links”: { “events” : { “href”: “/eventsapi/performers/8”, “type” : “application/vnd.siren+json” } /* … other fields … */ } Events API Artists API

Slide 54

Slide 54 text

Inter API Communication - Inter API calls are easily supported in REST APIs based of the media type semantics. - In fact, Hypermedia is the under- pinning architectural style of the web. GET /eventsapi/events/8 HTTP/1.1 ContentType: application/vnd.siren+json { "class": [ “event" ], "properties": { “startDate": “2017-09-18T15:00:00+10:00”, “endDate: “2017-08-18T16:00:00+10:00”, “availableTicketCount": 42 }, /* … other fields … */ } Events API Artists API

Slide 55

Slide 55 text

{ “data”: { “artist” : { “events”: [ { “url”: “/eventsapi/performers/8” } ] } } } Inter API Communication - There is no easy way to federate calls across GraphQL schemas. - Ideally model these as additional nodes and edges in the same GraphQL schema. - Failing this we must defer to ‘out of band’ sources such as API documentation. POST /graphql HTTP/1.1 { artist { events { url } } } Events API GraphQL API

Slide 56

Slide 56 text

Slide 57

Slide 57 text

Authentication & Authorization

Slide 58

Slide 58 text

GraphQL REST RPC Business Logic Authentication Authentication Authorization HTTP TCP based protocol

Slide 59

Slide 59 text

As a User, I want to be the only one permitted to see my personal details So that my right to privacy is respected

Slide 60

Slide 60 text

No content

Slide 61

Slide 61 text

No content

Slide 62

Slide 62 text

This approach works well for 1st party systems. What about 3rd party systems with delegated access?

Slide 63

Slide 63 text

Authentication Authentication HTTP TCP based protocol REST RPC Coarse Grained Authorization GraphQL Business Logic Authorization

Slide 64

Slide 64 text

No content

Slide 65

Slide 65 text

No content

Slide 66

Slide 66 text

Image by toffehoff via https://www.flickr.com/photos/toffehoff/244870161/ So far we have been pulling data what if we could we enable the pushing of data

Slide 67

Slide 67 text

As a User, I want to be notified when my favourite artists release albums So that I can keep to up to date with the music that I love

Slide 68

Slide 68 text

Real Time APIs -Pull -Polling -Push -Live Queries (standard query with infinitely fast polling) -Subscriptions (event based)

Slide 69

Slide 69 text

Subscriptions RFC has been raised facebook/graphql#267

Slide 70

Slide 70 text

Event Based Subscriptions -Concept: Server pushes message to client when ‘something’ occurs -Read only -Expressed using GraphQL syntax -Not a replacement for GraphQL queries!

Slide 71

Slide 71 text

Client Request / Response GraphQL Business Domain

Slide 72

Slide 72 text

Subscriptions Client Request / Response GraphQL Events Bi-directional Transport Business Domain

Slide 73

Slide 73 text

Subscriptions Client Request / Response GraphQL Events Bi-directional Transport Business Domain Subscription Event

Slide 74

Slide 74 text

Example subscription workflow / use case User Admin GraphQL Server Connect to WS endpoint (ws://api.example.com/subscriptions)

Slide 75

Slide 75 text

Example subscription workflow / use case Subscribe to advertised event (http://api.example.com/graphql) subscription onAlbumAdded { albumAdded(userId: “1”) { album { title } artist { name } } } User Admin GraphQL Server Web socket connection open and waiting for published events

Slide 76

Slide 76 text

Example subscription workflow / use case User Admin mutation addAlbum { addAlbum(album: {title: "Cold Water Music", artistId: 1, labelId: 1 }) { artist { id name } } } Admin user adds new album using addAlbum mutation GraphQL Server Web socket connection open and waiting for published events

Slide 77

Slide 77 text

Album added event document pushed to client Example subscription workflow / use case User Admin { albumAdded: { album: { title: “Cold Water Music” } artist: { name: “Aim” } } } GraphQL Server

Slide 78

Slide 78 text

Low friction development of GraphQL APIs

Slide 79

Slide 79 text

GraphQL Dev Workflow - Front end and back end teams agree on schema. - UI is developed using mocked data based on schema - API is built out with any changes being communicated to front end team - Integrate front and back ends - Ship - Repeat Schema App Api Product

Slide 80

Slide 80 text

Slide 81

Slide 81 text

Slide 82

Slide 82 text

Slide 83

Slide 83 text

{ real { data } fake { data } } { real { data } } { real { data: “resolved” } } { real { data: “resolved” } fake { data: “stubbed” } } IDL application/graphql application/json GraphQL Faker facilitates low friction experimentation when modelling schema. It’s quicker to change IDL than the API.

Slide 84

Slide 84 text

GraphQL Faker Demo https://github.com/APIs-guru/graphql-faker

Slide 85

Slide 85 text

Query execution telemetry is vital for identifying performance bottlenecks

Slide 86

Slide 86 text

Build support for a phased release approach for API changes

Slide 87

Slide 87 text

Takeaways

Slide 88

Slide 88 text

Thank you!

Slide 89

Slide 89 text

Resources - Official Docs: http://graphql.org - Specification: https://github.com/facebook/graphql - Reference: https://github.com/graphql/graphql-js - Community: http://graphql.org/community - Awesome List: https://github.com/chentsulin/awesome-graphql - Humble Additions - Code: https://github.com/robcrowley/graphql-demo - Slides: https://bit.ly/ndcsydney-graphql