Slide 1

Slide 1 text

goodapi.co Zdenek “Z” Nemec goodapi.co REST vs. GraphQL Critical Review

Slide 2

Slide 2 text

goodapi.co I help businesses build APIs Zdenek “Z” Nemec @zdne zdne1

Slide 3

Slide 3 text

goodapi.co https://supermodel.io

Slide 4

Slide 4 text

goodapi.co REST & GraphQL

Slide 5

Slide 5 text

goodapi.co REST & GraphQL • GraphQL: graphql.org • REST: internet • Protocols, frameworks, languages and architectural styles • API Paradigms • HTTP protocol for purpose of this critical review

Slide 6

Slide 6 text

goodapi.co THIS IS A CRITICAL REVIEW

Slide 7

Slide 7 text

goodapi.co REVIEWS TO DATE

Slide 8

Slide 8 text

goodapi.co REVIEWS TO DATE

Slide 9

Slide 9 text

goodapi.co REVIEWS TO DATE

Slide 10

Slide 10 text

goodapi.co REVIEWS TO DATE “…then GraphQL is the new REST” Both REST vs. SOAP & GraphQL vs. REST “movements” are clearly fueled by unhappy, overlooked and over-served API consumers.

Slide 11

Slide 11 text

goodapi.co API COMMUNITY IS STILL RELATIVELY SMALL. WE SHOULD WORK TOGETHER.

Slide 12

Slide 12 text

goodapi.co WHICH ONE IS THE BEST? REST vs. GraphQL

Slide 13

Slide 13 text

goodapi.co FRAMEWORK FOR COMPARING API PARADIGMS– ARCHITECTURAL STYLES

Slide 14

Slide 14 text

goodapi.co ARCHITECTURAL STYLE

Slide 15

Slide 15 text

goodapi.co ARCHITECTURAL STYLE IS A SET OF CONSTRAINTS THAT IMPLY SYSTEM WITH CERTAIN PROPERTIES applied CONSTRAINTS imply PROPERTIES

Slide 16

Slide 16 text

goodapi.co WHAT CONSTRAINT I AM PICKING AND WHAT IS ITS INDUCED PROPERTY? DECOUPLED implies EVOLVABLE STATELESS implies RELIABLE and SCALEABLE UNIFORM INTERFACE implies DEGRADED EFFICIENCY but also SIMPLICITY

Slide 17

Slide 17 text

goodapi.co ARCHITECT

Slide 18

Slide 18 text

goodapi.co ROLE OF API ARCHITECT IS TO UNDERSTAND MANY PARADIGMS AND TO PICK THE RIGHT ONE FOR THE TASK “Architect knows something about everything, an engineer knows everything about one thing.”

Slide 19

Slide 19 text

goodapi.co FOR A GIVEN TASK? WHICH ONE IS THE BEST REST vs. GraphQL

Slide 20

Slide 20 text

goodapi.co goodapi.co API PARADIGMS API ARCHITECTURAL STYLES

Slide 21

Slide 21 text

goodapi.co API PARADIGMS Web APIs Query APIs Streaming APIs RPC APIs Flat File

Slide 22

Slide 22 text

goodapi.co Paradigm Shift CUSTOMER-SPECIFIC APIS one-to-one: few large established customers First Wave (2000) GENERIC APIS one-to-many: many mid- or small- size customers Second Wave (2010) AUTONOMOUS APIS many-to-many & machine-to-machine: automatic, later autonomous APIs Third Wave (2020)

Slide 23

Slide 23 text

goodapi.co goodapi.co AUTONOMOUS APIS

Slide 24

Slide 24 text

goodapi.co THE (FORTUNE 500) WORLD STILL RUNS ON SOAP, EDI OR FTP, NOT REST OR GRAPHQL However…

Slide 25

Slide 25 text

goodapi.co THE CHOICE OF PARADIGM SHOULD ALWAYS BE FUNCTION OF YOUR CONSTRAINTS

Slide 26

Slide 26 text

goodapi.co CONSTRAINTS

Slide 27

Slide 27 text

goodapi.co COLONIAL ARCHITECTURE “Houses were colonial because of the colonists were colonial and had colonial constraints” “I really like colonial houses, I think I’ll build one…”

Slide 28

Slide 28 text

goodapi.co “I really like colonial houses REST APIs I think I’ll build one…” “I really like colonial houses GraphQL APIs I think I’ll build one…”

Slide 29

Slide 29 text

goodapi.co CONSTRAINTS 1.Business Constraints customer-related, business requirements, product requirements 2.Complexity Constraints implications of distributed system complexity, evolution qualities 3.Domain Constraints domain-specific limitations, regulations, environments 4.Cultural Constraints Conway’s law, knowledge, (human) resources, peer-pressure, trendiness

Slide 30

Slide 30 text

goodapi.co CONSTRAINTS Ecosystem Properties 1.Business Constraints 2.Complexity Constraints 3.Domain Constraints 4.Cultural Constraints Distributed System Properties

Slide 31

Slide 31 text

goodapi.co PROPERTIES

Slide 32

Slide 32 text

goodapi.co Distributed System Properties 1.Performance • network performance • network efficiency • user-perceived 2.Scalability • size complexity Distributed System Properties 3.Simplicity • of the uniform interface • user-perceived • task-structure • unpredictability • algorithmic • chaotic REST induced

Slide 33

Slide 33 text

goodapi.co Distributed System Properties 4.Modifiability • evolvability • extensibility • customizability • configurability • reusability 5.Visibility • monitoring • security • caching Distributed System Properties 6.Portability • different environments • code with data 7.Reliability • susceptibility to failure • ability to recover REST induced

Slide 34

Slide 34 text

goodapi.co Distributed System Properties 8.Discoverability • design-time • runtime-time 9.Type-safety 10.Ease of Development • server • client Distributed System Properties 11.Costs effectivity • time to market • development costs • maintenance costs • cost of change

Slide 35

Slide 35 text

goodapi.co Distributed Ecosystem Properties Ecosystem Properties 1.Active Community 2.Tooling • client • server • API management • Developer experience 3.Ecosystem Maturity 4.Resources • books • articles • on-boarding tutorials 5.Enterprise Readiness

Slide 36

Slide 36 text

goodapi.co THESE ARE THE PROPERTIES I GENERALLY CARE ABOUT

Slide 37

Slide 37 text

goodapi.co THESE PROPERTIES ARE TOO BROAD TO BE NEEDED BY EVERY API If you are building API between a single page app and your backend, chances are you do not many of those (e.g. scaleability)

Slide 38

Slide 38 text

goodapi.co YOUR CONSTRAINTS WILL IMPLY ANOTHER SET OF PROPERTIES

Slide 39

Slide 39 text

goodapi.co CRITICAL REVIEW

Slide 40

Slide 40 text

goodapi.co REST APIs

Slide 41

Slide 41 text

goodapi.co REST • Hard to get started with • Difficult to master • Rare to find Successful implementations are rare outside of WWW • Unparalleled scaleability, evolvability and discoverability if pulled properly

Slide 42

Slide 42 text

goodapi.co REST Constraints & induced Properties 1.Client-Server 2.Stateless 3.Cacheable 4.Layered System 5.Code on Demand (optional) 6.Uniform Interface 1.Identification of Resources 2.Resource Representations 3.Self-descriptive Messages 4.HATEOAS 1.Performance 2.Scalability 3.Simplicity 4.Modifiability 5.Visibility 6.Portability 7.Reliability

Slide 43

Slide 43 text

goodapi.co REST PROVIDE BENEFITS… …BUT COME WITH COSTS • Will scale indefinitely • High performance (especially over HTTP2) • Proven for decades • Works with any representation and media type • Affordance-centric (design maturity) • Server-driven application state (server tells you what you can call an when) • Full decoupling of client and server enabling the independent evolution • Links across APIs • Huge entry barrier in training and learning, which most of us never overcome • The big change in the paradigm shift from SOAP, challenging for enterprises to change the mindset • Requires clients to play along, requires discipline on all sides • Poor or no tooling for clients • Limiting API description formats • Challenging to keep consistency and any governance Icons by martinfowler.com

Slide 44

Slide 44 text

goodapi.co so-called-REST APIs

Slide 45

Slide 45 text

goodapi.co so-called-REST • Most common type of generic APIs by far • Usually follows HTTP-induced constraints • But many instances does not even follow HTTP protocol (concern separation, Amundsen & Richardson maturity models) • Requires significant amount understanding of HTTP protocol on both client and serve side • Independent evolution is impossible or, at least, painful • Benefits from internet infrastructure–scaleability

Slide 46

Slide 46 text

goodapi.co REST Constraints & induced Properties in so-called-REST APIs 1.Client-Server 2.Stateless 3.Cacheable 4.Layered System 5.Code on Demand (optional) 6.Uniform Interface 1.Identification of Resources 2.Resource Representations 3.Self-descriptive Messages 4.HATEOAS 1.Performance 2.Scalability 3.Simplicity 4.Modifiability 5.Visibility 6.Portability 7.Reliability

Slide 47

Slide 47 text

goodapi.co so-called-REST PROVIDE BENEFITS... …BUT COME WITH COSTS • Will scale well when following HTTP • High performance if well design (especially over HTTP2) • Proven for by all RESTful APIs • Works with any representation and media type • Mature tooling available • Sill some entry barrier in training and learning • Difficult to evolve • Challenging to keep consistency and any governance • Type safety and contract driven is not required but optional Icons by martinfowler.com

Slide 48

Slide 48 text

goodapi.co GraphQL APIs

Slide 49

Slide 49 text

goodapi.co “The more specific a design idea is, the greater its appeal is likely to be” – Matthew Frederick

Slide 50

Slide 50 text

goodapi.co GraphQL • Easy to get started with • Remote data access, essentially simplified, vendor-agnostic SQL • Unparalleled tooling and on-boarding, DX and time-to-market • Ignoring the whole internet infrastructure with POST tunneling • Bike shedding (authentication, content negotiation, pagination, and other rate limiting has to be reinvented) • Scaleability issues (thanks to no infrastructure caching) • Tight coupling of clients with servers (data structure)

Slide 51

Slide 51 text

goodapi.co GraphQL PROVIDE BENEFITS... …BUT COME WITH COSTS • Easy to start with • Time to market for servers and clients • Amazing developer experience • Contract-driven by nature • Built-in introspection • Easier to keep consistent and to govern • Closer to WS / SQL data access make the paradigm shift easier than with REST • Design can be deferred to later (which might be also a bad thing) • Neglects the problems of the distributed system • Server and clients coupled at the client programming time, application state is not driven by the server • Query optimization • Bikeshedding (content negotiation, network errors, caching, authentication) • Scaling, (server and client caching only) you can’t rely on existing caches • Throws away everything HTTP was figuring out for last 17 years • Limited media type support • Too few vendors in the ecosystem, the major one is pretending it owns the show Icons by martinfowler.com

Slide 52

Slide 52 text

goodapi.co OVERVIEW @zdne Full table will be available at my Induced Properties Comparison of Different Architectural Styles

Slide 53

Slide 53 text

goodapi.co NONE SHALL ESCAPE THE API DESIGN

Slide 54

Slide 54 text

goodapi.co API DESIGN In REST you have to go through the exercise of understanding the users’ needs before the API implementation. With GraphQL you can defer the moment of understanding how users consume your API until you start profiling the queries, evaluating their complexity and identifying the slow queries.

Slide 55

Slide 55 text

goodapi.co Good REST API is designed with use-cases in mind (affordance-centric design) GraphQL gives you seemingly generic API (remote data access)

Slide 56

Slide 56 text

goodapi.co EITHER WAY YOU HAVE TO UNDERSTAND THE USER NEEDS AND DESIGN YOUR API AND ITS IMPLEMENTATION ACCORDINGLY. IT WOULD BE FOOLISH TO THINK YOU CAN CREATE A WELL-PERFORMANT API FOR EVERY USE CASE. YOU HAVE TO MAKE DESIGN CHOICES. “The more specific a design idea is, the greater its appeal is likely to be”

Slide 57

Slide 57 text

goodapi.co CASE-EXAMPLES

Slide 58

Slide 58 text

goodapi.co HR TEAM AND PAYROLL PROCESSING Flat File

Slide 59

Slide 59 text

goodapi.co BACKEND API FOR SPA GraphQL API

Slide 60

Slide 60 text

goodapi.co COMPLEX API LANDSCAPE REST APIs

Slide 61

Slide 61 text

goodapi.co CONCLUSION

Slide 62

Slide 62 text

goodapi.co • Build system that lasts • In need of content negotiation (language) • Precise authentication, authorization rate limiting • Interlink resources between APIs • Use mixed media types • Care about scaleability Use REST if Rules of Thumb

Slide 63

Slide 63 text

goodapi.co • Talking to yourself (frontend–backend) • Instead of so-called-REST • Short term projects • Uncertain use-cases • Just access data without the need for infra caching • Amazing DX with little effort Use GraphQL if Rules of Thumb

Slide 64

Slide 64 text

goodapi.co Do not build so-called-REST APIs Rules of Thumb

Slide 65

Slide 65 text

goodapi.co ALWAYS PICK BASED ON YOUR CONSTRAINTS, NOT SOMEBODY ELSE’S YOU ARE UNIQUE.

Slide 66

Slide 66 text

goodapi.co GOOD API INDEPENDENT API CONSULTING WE ARE HIRING

Slide 67

Slide 67 text

PHOTOS BY UNSPLASH.COM

Slide 68

Slide 68 text

goodapi.co OVER-FETCHING • GraphQL enthusiasts claims it helps with REST over- fetching REST API with many fields in response is probably poorly designed • REST has the same functionality with sparse field sets • Both GraphQL and REST sparse field sets hurts caching Which one is faster: A requests that drops dozen of unnecessary fields or one that hits the cache? first call 220ms (cache miss) subsequent calls 160ms (cache hit) -vs- first and subsequent calls 200ms (no cache)

Slide 69

Slide 69 text

goodapi.co WHAT QUALITIES ARE YOU BUYING WHEN YOU SAY YES? WHAT PROPERTIES ARE YOU LOOSING WHEN YOU SAY NO TO OTHER STYLES?

Slide 70

Slide 70 text

goodapi.co

Slide 71

Slide 71 text

goodapi.co

Slide 72

Slide 72 text

goodapi.co

Slide 73

Slide 73 text

goodapi.co ARCHITECTURAL PROPERTIES OF KEY INTEREST

Slide 74

Slide 74 text

goodapi.co DISTRIBUTED SYSTEM PROPERTIES