REST vs. GraphQL: Critical Review

Cb2527e0c321fc1eb6753c06f45da93c?s=47 Z
October 23, 2018

REST vs. GraphQL: Critical Review

GraphQL has made an excellent entree on the API scene. It is reintroducing the original concepts of RPC-style architecture with a revolutionary API consumer-oriented approach. It brought a new option to the stalled waters of RESTful APIs. But more importantly, GraphQL brought back the principal question: What is the right API architectural style for my project?

If you are building an API, this talk should give you enough of the theoretical background to make the right API-decision for your product.

In this talk, we will take a critical look at predominant API architectural style – RESTful APIs and put it in contrast to GraphQL and Hypermedia APIs. We will discuss the expected properties of distributed systems, the consequences of choosing a particular API style, and reflect these findings in the pros and cons of the popular methods.

The keynote I've gave at Nordic APIs Platform Summit 2018, Stockholm

https://nordicapis.com/?post_type=sessions&p=9162

Cb2527e0c321fc1eb6753c06f45da93c?s=128

Z

October 23, 2018
Tweet

Transcript

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

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

    zdne1
  3. goodapi.co https://supermodel.io

  4. goodapi.co REST & GraphQL

  5. 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
  6. goodapi.co THIS IS A CRITICAL REVIEW

  7. goodapi.co REVIEWS TO DATE

  8. goodapi.co REVIEWS TO DATE

  9. goodapi.co REVIEWS TO DATE

  10. 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.
  11. goodapi.co API COMMUNITY IS STILL RELATIVELY SMALL. WE SHOULD WORK

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

  13. goodapi.co FRAMEWORK FOR COMPARING API PARADIGMS– ARCHITECTURAL STYLES

  14. goodapi.co ARCHITECTURAL STYLE

  15. goodapi.co ARCHITECTURAL STYLE IS A SET OF CONSTRAINTS THAT IMPLY

    SYSTEM WITH CERTAIN PROPERTIES applied CONSTRAINTS imply PROPERTIES
  16. 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
  17. goodapi.co ARCHITECT

  18. 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.”
  19. goodapi.co FOR A GIVEN TASK? WHICH ONE IS THE BEST

    REST vs. GraphQL
  20. goodapi.co goodapi.co API PARADIGMS API ARCHITECTURAL STYLES

  21. goodapi.co API PARADIGMS Web APIs Query APIs Streaming APIs RPC

    APIs Flat File
  22. 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)
  23. goodapi.co goodapi.co AUTONOMOUS APIS

  24. goodapi.co THE (FORTUNE 500) WORLD STILL RUNS ON SOAP, EDI

    OR FTP, NOT REST OR GRAPHQL However…
  25. goodapi.co THE CHOICE OF PARADIGM SHOULD ALWAYS BE FUNCTION OF

    YOUR CONSTRAINTS
  26. goodapi.co CONSTRAINTS

  27. 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…”
  28. 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…”
  29. 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
  30. goodapi.co CONSTRAINTS Ecosystem Properties 1.Business Constraints 2.Complexity Constraints 3.Domain Constraints

    4.Cultural Constraints Distributed System Properties
  31. goodapi.co PROPERTIES

  32. 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
  33. 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
  34. 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
  35. 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
  36. goodapi.co THESE ARE THE PROPERTIES I GENERALLY CARE ABOUT

  37. 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)
  38. goodapi.co YOUR CONSTRAINTS WILL IMPLY ANOTHER SET OF PROPERTIES

  39. goodapi.co CRITICAL REVIEW

  40. goodapi.co REST APIs

  41. 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
  42. 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
  43. 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
  44. goodapi.co so-called-REST APIs

  45. 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
  46. 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
  47. 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
  48. goodapi.co GraphQL APIs

  49. goodapi.co “The more specific a design idea is, the greater

    its appeal is likely to be” – Matthew Frederick
  50. 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)
  51. 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
  52. goodapi.co OVERVIEW @zdne Full table will be available at my

    Induced Properties Comparison of Different Architectural Styles
  53. goodapi.co NONE SHALL ESCAPE THE API DESIGN

  54. 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.
  55. goodapi.co Good REST API is designed with use-cases in mind

    (affordance-centric design) GraphQL gives you seemingly generic API (remote data access)
  56. 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”
  57. goodapi.co CASE-EXAMPLES

  58. goodapi.co HR TEAM AND PAYROLL PROCESSING Flat File

  59. goodapi.co BACKEND API FOR SPA GraphQL API

  60. goodapi.co COMPLEX API LANDSCAPE REST APIs

  61. goodapi.co CONCLUSION

  62. 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
  63. 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
  64. goodapi.co Do not build so-called-REST APIs Rules of Thumb

  65. goodapi.co ALWAYS PICK BASED ON YOUR CONSTRAINTS, NOT SOMEBODY ELSE’S

    YOU ARE UNIQUE.
  66. goodapi.co GOOD API INDEPENDENT API CONSULTING WE ARE HIRING

  67. PHOTOS BY UNSPLASH.COM

  68. 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)
  69. goodapi.co WHAT QUALITIES ARE YOU BUYING WHEN YOU SAY YES?

    WHAT PROPERTIES ARE YOU LOOSING WHEN YOU SAY NO TO OTHER STYLES?
  70. goodapi.co

  71. goodapi.co

  72. goodapi.co

  73. goodapi.co ARCHITECTURAL PROPERTIES OF KEY INTEREST

  74. goodapi.co DISTRIBUTED SYSTEM PROPERTIES