BETTER APIS WITHThe Future of the Realtime Web
Josh Price @joshprice
GRAPHQL
STEPPING STONES TO FPLa
ngua
ge (E
lixir)
Strongly-Typed APIs (GraphQL)
GRAPHQL WAS
HERE?
http://whiteafrican.com/2008/05/12/crossing-the-mapping-chasm/
COMMON ISSUES WITH RESTA TAXONOMY OF
PERFORMANCE
UNDERFETCHING
COMMON ISSUES WITH REST
UNDERFETCHING
▸ N + 1 HTTP request problem
▸ eg. Fetched a Blog Post but not Comments
▸ Must make more requests to fulfil data requirements
▸ For complex views we saw 6-7 requests (usually serial)
▸ Have seen up to 25+ requests in the wild
OVERFETCHING
COMMON ISSUES WITH REST
OVERFETCHING
▸ Client wants a small subset of data from endpoint
▸ But gets everything regardless
▸ The addition of fields to a endpoint bloats payloads
▸ Create more endpoints, but this means more roundtrips
▸ Could create a homepage specific endpoint for each device, but harder to manage
BIG UPFRONT DESIGN
COMMON ISSUES WITH REST
BIG UPFRONT DESIGN NEEDED
▸ Need to anticipate all current and future clients’ needs
▸ ie Mobile v Web clients
▸ Could have multiple representations/endpoints
▸ Divergence of server code
▸ Keeping everything in sync is hard
HYPERMEDIA?
COMMON ISSUES WITH REST
HYPERMEDIA ISN’T ALWAYS APPLICABLE
▸ If you control the clients and the server
▸ Less useful for your web or mobile app calling a known API 1000x / sec
▸ Semantics are communicated out of the
▸ A self-describing, well-typed API is an alternative approach
GRAPHQL
GRAPHQL HISTORY
WHAT IS GRAPHQL?
▸ Language for defining schemas, types & queries
▸ It’s a specification for that language (like OpenAPI, Swagger)
▸ Developed by Facebook in 2012
▸ Used internally to improve mobile app performance
▸ Served 300B+ requests per day (1.6B DAU on mobile)
▸ Open sourced spec in mid 2015
DATA FETCHINGGENERALISED
EASIER TO BUILDGRAPHQL APIS ARE
EASIER TO CONSUMEGRAPHQL APIS ARE
PERFORMANCEBETTER
SELF DOCUMENTINGSELF DESCRIBING AND
CONSUMER DRIVEN CONTRACTS
EXPOSE YOUR DOMAIN MODEL VIA
ISOMORPHICQUERIES AND RESPONSES ARE
STRONGLY TYPED APISTYPES IN YOUR SCHEMA ==
EASIER EVOLUTIONBUILT-IN FIELD DEPRECATION MEANS
MYTHS & MISCONCEPTIONS
GRAPH DATABASEYOU DO NOT NEED A
QUERY LANGUAGETHIS IS NOT YOUR TYPICAL
LANGUAGE AGNOSTICNOT ONLY FOR JAVASCRIPT
HTTP OR JSONNOT DEPENDENT ON
DOES NOT REPLACE REST IT’S EASIER TO WORK WITH BUT
MAKES REST EASIERPOTENTIALLY
GRAPHQL CONCEPTSLET’S LEARN SOME
SCHEMAS, TYPES AND SCALARS
type Meetup { title: String! date: Date description: String url: URL! talks: [Talk!]! }
type Talk { title: String! description: Markdown presenter: Person! }
schema { query: Query mutation: Mutation }
GraphQL SDL
SCHEMAS, TYPES AND SCALARS
type Meetup { title: String! date: Date description: String url: URL! talks: [Talk!]! }
type Talk { title: String! description: String presenter: Person! }
schema { query: Query mutation: Mutation }
@desc "A meetup” object :meetup do @desc "The title of the meetup" field :title, non_null(:string)
@desc "The date of the meetup" field :date, :date
@desc "The description of the meetup" field :description, :string
@desc "The Meetup.com url" field :url, :string
@desc "The talks at the meetup" field :talks, list_of(:talk) end
GraphQL SDL Elixir with Absinthe
GRAPHQL CONCEPTS
RESOLVER FUNCTIONS FETCH YOUR DATA
▸ Resolver functions fetch (or update) data
▸ Called when query fields are matched against schema fields
▸ Return data or an error
▸ Can take arguments specified in schema
▸ Can take a context in from the query (ie current user for authentication and authorisation)
GRAPHQL CONCEPTS
RESOLVER FUNCTIONS (ELIXIR EXAMPLE)defmodule GraphqlSydney.GraphQL.Schema do use Absinthe.Schema alias GraphqlSydney.Events
import_types Absinthe.Type.Custom
query do @desc "Get the next meetup" field :next_meetup, type: :meetup do resolve fn _, _ -> {:ok, Events.next_meetup} end end
@desc "Get the previous meetups" field :previous_meetups, type: list_of(:meetup) do resolve fn _, _ -> {:ok, Events.past_meetups} end end end end
GRAPHQL CONCEPTS
QUERY PROCESSING PIPELINE
▸ Client send Query documents as Strings
▸ Server Parses into AST
▸ Validation of AST
▸ Query fields matched against Schema
▸ Matching resolver functions executed
▸ Data (and errors) returned to client as a Map
1 2
34CLIENT
DB
CMS
SIMPLE QUERY LIFECYCLE
Query (String)
Response (Map)
Data Fetching
Run Resolver
Functions
LET’S SEE IT IN ACTION!
QUERY: FETCH NEXT MEETUP
QUERY: AUTOCOMPLETE / AUTOCORRECTION
QUERY: FETCH NEXT MEETUP’S TALKS
QUERY: INLINE DOCUMENTATION
QUERY: MEETUP WITH TALKS AND PRESENTERS
GETTING STARTED
HOW TO GET STARTED WITH GRAPHQL
STEP 1: PICK A SERVER IMPLEMENTATION
▸ JavaScript reference implementation
▸ Apollo Server Tools
▸ Java / Scala (Sangria)
▸ .NET / F#
▸ Ruby / Python / PHP
▸ Elixir / Erlang
▸ Go / Rust / Haskell
HOW TO GET STARTED WITH GRAPHQL
STEP 2: WRITE YOUR SCHEMA
▸ Figure out your domain types
▸ Write top level queries for reads
▸ Add mutations for writes
▸ Subscriptions for reactive data changes
▸ Don’t forget field descriptions!
HOW TO GET STARTED WITH GRAPHQL
STEP 3: CHOOSE A CLIENT
▸ Relay Modern
▸ Declare data requirements of UI component as query fragments
▸ Sends a single query
▸ Render collects query fragments in the render tree
▸ Caches objects by unique ID
▸ Added graph convention of nodes and edges
▸ Pagination metadata, etc
▸ Not actually part of the spec and can be confusing
HOW TO GET STARTED WITH GRAPHQL
STEP 3: CHOOSE A CLIENT
▸ Apollo 2.0
▸ Bit simpler than Relay, no graph conventions
▸ Hand rolled queries for each view
▸ Handles client side caching
▸ Probably easiest to start here
▸ Also has native iOS and Android client libs
HOW TO GET STARTED WITH GRAPHQL
STEP 4: PROFIT
▸ Start with read only first
▸ Shim existing REST APIs
▸ Frontend and Backend need to be on board
▸ Easy to experiment
▸ Try it out on new non-critical path projects
THINGS TO WATCH OUT FOR
THINGS TO WATCH OUT FOR
COMPLEX AND PATHOLOGICAL QUERIES
▸ Denial of Service possible for slow queries
▸ Be careful with exposing sorting, filtering and aggregation
▸ ie Don’t expose a sort field without an index
▸ Limit query depth and/or complexity
▸ Not all implementations have this though
▸ Instrumentation can alleviate this
THINGS TO WATCH OUT FOR
AVOID “STRINGLY TYPING”
▸ It’s very easy overuse plain String types
▸ You lose information: makes mocking harder
▸ There are no type aliases in the spec (yet)
▸ Can write your own custom Scalars (impl specific)
▸ Fine-grained “Micro-types” are useful
▸ ie URL, Email, Markdown, Name, Money, etc
THINGS TO WATCH OUT FOR
NO HTTP CACHING
▸ Can send queries by GET
▸ POST is preferred
▸ Can’t use standard HTTP caching
▸ Varnish, Squid, etc
▸ Can cache elsewhere however
▸ Client, Resolvers, Data Store, etc
RICH TOOLING ECOSYSTEM
EXPORATION & VISUALISATION
GRAPHQL SERVER ANALYTICS
QUERY EXECUTION TRACING
INTEGRATED CACHE MANAGEMENT
ERROR TRACKING
SCHEMA ANALYSIS
SCHEMA STITCHING AND COMPOSITION
SCHEMA COMPOSITION
SCHEMA STITCHING
GRAFT
TOOL ECOSYSTEM
SCHEMA COMPOSITION TOOLS
▸ Apollo Schema Stitching
▸ https://dev-blog.apollodata.com/graphql-schema-stitching-8af23354ac37
▸ Gramps the IBM microservice API composition framework
▸ https://github.com/gramps-graphql/gramps
▸ GraphQL Weaver
▸ https://github.com/AEB-labs/graphql-weaver
API MOCKING
GRAPHQL STACKS
CMS BACKENDS
GRAPHQL BACKENDS AS A SERVICE
REALTIME APIS WITH SUBSCRIPTIONS
REACTIVE BACKENDSHTTP/2 PUSH AND THE RISE OF
HAS GRAPHQL CROSSED THE CHASM?
GRAPHQL IS
HERE
http://whiteafrican.com/2008/05/12/crossing-the-mapping-chasm/
NEXT STEPS
RESOURCES
▸ http://graphql.org/
▸ https://github.com/chentsulin/awesome-graphql
▸ https://www.apollographql.com/
▸ https://facebook.github.io/relay/
▸ GraphQL Summit Videos
▸ https://www.youtube.com/playlist?list=PLpi1lPB6opQywks7yYYs5jJAIRI3faRTm
Top Related