Slide 1
Slide 1 text
REST vs
GraphQL
Illustrated examples using API Platform
Slide 2
Slide 2 text
Kévin Dunglas
Founder of Les-Tilleuls.coop
Symfony Core Team
(PropertyInfo, WebLink, Serializer, autowiring, PSR-7 Bridge…)
API Platform creator
@dunglas
Slide 3
Slide 3 text
Les-Tilleuls.coop
Self-managed company since 2011
100% owned by employees
25 people, 97% growth in 2016
Hiring in Paris and Lille: [email protected]
Slide 4
Slide 4 text
The API Platform
framework
Slide 5
Slide 5 text
No content
Slide 6
Slide 6 text
or
Slide 7
Slide 7 text
No content
Slide 8
Slide 8 text
JSON-LD+Hydra (default)
OpenAPI (default)
GraphQL
JSONAPI
HAL + API Problem
YAML, JSON, CSV, XML
Supported Formats
Slide 9
Slide 9 text
No content
Slide 10
Slide 10 text
Install
Slide 11
Slide 11 text
The Distribution
$ docker-compose up
Slide 12
Slide 12 text
No content
Slide 13
Slide 13 text
No content
Slide 14
Slide 14 text
No content
Slide 15
Slide 15 text
All components: API, Schema gen, Admin, Client gen
PHP and JS Docker images, Docker Compose env
Postgres server
Varnish, invalidation-based cache mechanism enabled
HTTPS and HTTP/2 dev reverse proxy
Helm chart to deploy in Kubernetes clusters (GKE…)
What’s Inside
Slide 16
Slide 16 text
Alternative: use Flex
$ composer create-project \
symfony/skeleton my-api
$ cd my-api
$ composer req api
$ php -S 127.0.0.1:8000 -t public
Slide 17
Slide 17 text
• Only the API component
• Minimalist
Slide 18
Slide 18 text
Enabling the
GraphQL Support
Slide 19
Slide 19 text
Install GraphQL support
$ composer req \
webonyx/graphql-php
Slide 20
Slide 20 text
No content
Slide 21
Slide 21 text
No content
Slide 22
Slide 22 text
GraphQL?
Slide 23
Slide 23 text
No content
Slide 24
Slide 24 text
No content
Slide 25
Slide 25 text
No content
Slide 26
Slide 26 text
No content
Slide 27
Slide 27 text
No content
Slide 28
Slide 28 text
A data query language
Specifically designed for web APIs…
…as an alternative to REST
Open format with a formal specification
Perfect as an API gateway (aggregate data from services)
Released by Facebook in 2015
Service oriented
GraphQL
Slide 29
Slide 29 text
© graphql.org
Slide 30
Slide 30 text
© graphql.org
Slide 31
Slide 31 text
queries
mutations
subscriptions (❌ not supported in PHP)
type system, introspection
errors (limited)
multiple queries in one request (parallelization)
Main Features
Slide 32
Slide 32 text
De-facto standard for GraphQL servers
Created by Facebook for the Relay library
Node (super type, like Object in Java)
Object Identification: unique identifier across types
Connections: structure for pagination
Mutations format
Server Specification
Slide 33
Slide 33 text
Example:
the GitHub API
Slide 34
Slide 34 text
No content
Slide 35
Slide 35 text
No content
Slide 36
Slide 36 text
Defining REST
Slide 37
Slide 37 text
An architectural style for web services
Defined in Roy Fielding’s thesis in 2000
Leverage the HTTP protocol
True REST APIs are hypermedia (HATEOAS)
Resource oriented
REpresentational
State Transfer
Slide 38
Slide 38 text
W3C Standards
Slide 39
Slide 39 text
Map JSON properties to an ontology
Perfect for hypermedia APIs
W3C standard (2014), as HTML, CSS…
Compatible with existing semantic web standards and
tools (RDF, OWL, SPARQL, triple stores, Apache
Jena…)
JSON for Linked Data
Slide 40
Slide 40 text
Global and open vocabulary
Define types, properties and enumerations
~600 types: Person, Place, Organization, Event…
Extensible
Preferred encoding: JSON-LD
W3C community group started by Google, Microsoft, Yahoo and Yandex
Slide 41
Slide 41 text
Format for interoperable, hypermedia APIs
Built on top of JSON-LD, compatible with schema.org
In-band API documentation
Resources, properties, operations, collections, templated
links (filters), pagination, errors
Draft of a potential W3C specification (community group)
Slide 42
Slide 42 text
Example:
Google Knowledge
Graph API
Slide 43
Slide 43 text
No content
Slide 44
Slide 44 text
Alternative
Formats
Slide 45
Slide 45 text
Alternative Formats
OpenAPI (formerly Swagger)
Slide 46
Slide 46 text
Community format to build hypermedia web APIs
Simpler and easier to implement than Hydra+JSON-LD…
…but less powerful (no RDF nor schema.org compat)
Pagination, filtering, sparse fieldsets, compound docs,
errors…
Limited type system, no introspection
Experimental extensions
Slide 47
Slide 47 text
API doc format (describe RESTful contracts)
Path, operations, content negotiation…
Type system built with JSON Schema
Request/response formats up to you: JSON, XML…
Can partially describe JSON-LD and JSONAPI
OpenAPI (formerly Swagger)
Slide 48
Slide 48 text
Schema and Types
Slide 49
Slide 49 text
No content
Slide 50
Slide 50 text
No content
Slide 51
Slide 51 text
GraphQL Usage
Slide 52
Slide 52 text
No content
Slide 53
Slide 53 text
No content
Slide 54
Slide 54 text
Describe the data that can be queried
Expose operations (queries, mutations)
Made the API auto-discoverable (in-band docs)
Allow to develop smart clients (API agnostic)
GraphQL Schema
Slide 55
Slide 55 text
Hydra Documentation
Slide 56
Slide 56 text
No content
Slide 57
Slide 57 text
Capabilities similar to GraphQL’s Schema
Leverage RDF and OWL ()
Describe API’s types and supported REST operations
Unlike GraphQL:
API interoperability at web scale (hypermedia)
ability to use open vocabularies (schema.org)
JSON-LD/Hydra Vocab
Slide 58
Slide 58 text
No content
Slide 59
Slide 59 text
Alternative:
OpenAPI
Slide 60
Slide 60 text
Data fetching:
REST
Slide 61
Slide 61 text
new request
Slide 62
Slide 62 text
Data fetching:
GraphQL
Slide 63
Slide 63 text
+ REST compatibility
(API Platform specific)
Slide 64
Slide 64 text
Declarative and elegant query language
The client tells exactly what it needs
1 query (vs N with REST) to retrieve all required data
Solve under-fetching and over-fetching problem
Require a specific query parser, but returns JSON
No response/request parity: you cannot post a previously
retrieved then updated document
GraphQL
Slide 65
Slide 65 text
Data fetching:
Compound Docs
Slide 66
Slide 66 text
No content
Slide 67
Slide 67 text
Solve the N requests problem
The server is still rigid: the client’s request must be known
Don’t solve the under/over-fetching problem
Slide 68
Slide 68 text
Data fetching:
Sparse Fieldsets
Slide 69
Slide 69 text
No content
Slide 70
Slide 70 text
Solve the N requests problem
Solve the under/over fetching problem
Can be subject to problems with RDMS (more on this later)
Less explicit and elegant than GraphQL but…
Slide 71
Slide 71 text
PHP
JavaScript
Slide 72
Slide 72 text
Filtering
Slide 73
Slide 73 text
No content
Slide 74
Slide 74 text
REST
Slide 75
Slide 75 text
No content
Slide 76
Slide 76 text
GraphQL
Slide 77
Slide 77 text
Alternative REST format
Describe an advanced query language
Batch support
Not implemented (yet) in API Platform
Alternative:
Slide 78
Slide 78 text
Sorting
Slide 79
Slide 79 text
No content
Slide 80
Slide 80 text
REST
Slide 81
Slide 81 text
No content
Slide 82
Slide 82 text
GraphQL
Slide 83
Slide 83 text
Pagination
Slide 84
Slide 84 text
REST
Slide 85
Slide 85 text
No content
Slide 86
Slide 86 text
GraphQL
Slide 87
Slide 87 text
REST: configurable items per page
Slide 88
Slide 88 text
Changing States
Slide 89
Slide 89 text
REST
Support for compound documents
Ex: update both a book and an author in 1 request
Slide 90
Slide 90 text
GraphQL
Slide 91
Slide 91 text
No content
Slide 92
Slide 92 text
Logs
Slide 93
Slide 93 text
REST
Slide 94
Slide 94 text
GraphQL
Slide 95
Slide 95 text
Caching
Slide 96
Slide 96 text
GET responses are generated only 1 time, then served
by Varnish
Responses are tagged with IRIs (URLs) of resources
they contain
When a write operation occurs cached responses
containing stale data are purged
Support only REST (for now)
API Platform Built-in Cache
Slide 97
Slide 97 text
Most GraphQL clients use POST (=no HTTP cache)
Even with GET: high cache miss rate
Similar problem for sparse fieldsets
If most requests are similar:
A HTTP cache layer limits the over-fetching problem
Cache Considerations
Slide 98
Slide 98 text
Server application cache (ex: Doctrine data cache)
HTTP server-side cache (ex: Varnish)
HTTP client-side cache (ex: browser)
Client application cache (ex: local storage)
REST Cache Layers
Slide 99
Slide 99 text
Server application cache (ex: Doctrine data cache)
HTTP server-side cache (ex: Varnish)
HTTP client-side cache (ex: browser)
Client application cache (ex: local storage)
GraphQL Cache Layers
Slide 100
Slide 100 text
RDMS Performance
Slide 101
Slide 101 text
API Platform tries to optimize SQL queries, (adds
relevant joins), for both REST and GraphQL
Dynamic requests (GraphQL, sparse fieldsets) will
most likely not hit the indexes
monitor frequent slow queries
use more adapted DB: Neo4J, ElasticSearch…
With GraphQL, request can quickly become huge
RDMS Performance
Slide 102
Slide 102 text
Security &
Reliability
Slide 103
Slide 103 text
Industry recommendations
Out of the box implem by API Platform
Very large history and research
REST: OWASP SCS
Slide 104
Slide 104 text
Fewer feedback and history
Non-obvious security protection:
timeout?
maximum query depth?
maximum query complexity?
More sensitive to DDOS attacks
GraphQL Security
Slide 105
Slide 105 text
No content
Slide 106
Slide 106 text
(No) Versionning
Slide 107
Slide 107 text
GraphQL promotes deprecation over real versioning
Good practice with REST too: API evolution strategy
JSON-LD/Hydra: document deprecation with OWL
Not supported in API Platform yet (contrib? ❤)
No Versionning
Slide 108
Slide 108 text
Client-side
Slide 109
Slide 109 text
GraphQL: great, mature low-level libraries for React
Apollo Client (community)
Relay (Facebook)
Hydra: younger client-side ecosystem
api-platform/api-doc-parser: low level doc parser
api-platform/client-generator: PWA & native app
generator (React, React Native, Vue.js)
api-platform/admin: automatic React admin interface
Client-side
Slide 110
Slide 110 text
The Developper
Ethical Responsibility
Slide 111
Slide 111 text
Linked Data GraphQL
Origin Scientific
community
Facebook
Data
access
Open data Information silo
Interop Global and built-in Partial
Best suited
for
Decentralized
systems
(the world wide
web)
Centralized
systems
Slide 112
Slide 112 text
No content
Slide 113
Slide 113 text
Summary
Slide 114
Slide 114 text
Awesome, elegant query language
Perfect for: very dynamic or different clients
Real-time support (but not in PHP)
Ability to query unrelated data easily
Limited HTTP compat (cache, logs, content negot…)
Not easy to implement: parser, security, caching, perf…
GraphQL
Slide 115
Slide 115 text
Modern formats have similar features than GraphQL
sparse fieldsets, batch endpoints (ODATA)…
Mature and robust solution
Leverage HTTP (cache, content-negotiation, logs,
security…)
REST
Slide 116
Slide 116 text
Public and open API: REST
Private API for dynamic clients: GraphQL
API Platform:
Create both with the same code
The GraphQL API is compatible with Linked Data/REST
Use Both?
Slide 117
Slide 117 text
api-platform/api-platform @ApiPlatform
Thanks!
Now, the questions…
api-platform.com
Slide 118
Slide 118 text
Internals
Slide 119
Slide 119 text
Design the API’s public data model as PHP classes
API Platform creates an intermediate representation:
resources, types, cardinalities, r/w, description…
Metadata are used to:
generate the schema (OpenAPI, Hydra, GraphQL…)
(de)serialize data in the selected format (JSON-LD,
GraphQL…)
The Internals
Slide 120
Slide 120 text
Interfaces to access and persist data (Doctrine, Mongo, Elastic…):
DataProvider
DataPersister
Automatic registration of REST routes and GraphQL endpoint
Serialization and validation rely on Symfony components
REST: no controllers, pass thru a set of SF kernel event’s listeners
Dependency Injection and service decoration everywhere
The Internals (cont.)
Slide 121
Slide 121 text
No content