$30 off During Our Annual Pro Sale. View Details »

REST vs. GraphQL: Critical Review

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

Z

October 23, 2018
Tweet

More Decks by Z

Other Decks in Programming

Transcript

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

    View Slide

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

    View Slide

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

    View Slide

  4. goodapi.co
    REST & GraphQL

    View Slide

  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

    View Slide

  6. goodapi.co
    THIS IS A CRITICAL REVIEW

    View Slide

  7. goodapi.co
    REVIEWS TO DATE

    View Slide

  8. goodapi.co
    REVIEWS TO DATE

    View Slide

  9. goodapi.co
    REVIEWS TO DATE

    View Slide

  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.

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

  14. goodapi.co
    ARCHITECTURAL STYLE

    View Slide

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

    View Slide

  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

    View Slide

  17. goodapi.co
    ARCHITECT

    View Slide

  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.”

    View Slide

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

    View Slide

  20. goodapi.co
    goodapi.co
    API PARADIGMS
    API ARCHITECTURAL
    STYLES

    View Slide

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

    View Slide

  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)

    View Slide

  23. goodapi.co
    goodapi.co
    AUTONOMOUS
    APIS

    View Slide

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

    View Slide

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

    View Slide

  26. goodapi.co
    CONSTRAINTS

    View Slide

  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…”

    View Slide

  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…”

    View Slide

  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

    View Slide

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

    View Slide

  31. goodapi.co
    PROPERTIES

    View Slide

  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

    View Slide

  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

    View Slide

  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

    View Slide

  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

    View Slide

  36. goodapi.co
    THESE ARE THE
    PROPERTIES I GENERALLY
    CARE ABOUT

    View Slide

  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)

    View Slide

  38. goodapi.co
    YOUR CONSTRAINTS WILL
    IMPLY ANOTHER SET OF
    PROPERTIES

    View Slide

  39. goodapi.co
    CRITICAL REVIEW

    View Slide

  40. goodapi.co
    REST APIs

    View Slide

  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

    View Slide

  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

    View Slide

  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

    View Slide

  44. goodapi.co
    so-called-REST APIs

    View Slide

  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

    View Slide

  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

    View Slide

  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

    View Slide

  48. goodapi.co
    GraphQL APIs

    View Slide

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

    View Slide

  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)

    View Slide

  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

    View Slide

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

    View Slide

  53. goodapi.co
    NONE SHALL ESCAPE
    THE API DESIGN

    View Slide

  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.

    View Slide

  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)

    View Slide

  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”

    View Slide

  57. goodapi.co
    CASE-EXAMPLES

    View Slide

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

    View Slide

  59. goodapi.co
    BACKEND API FOR SPA
    GraphQL API

    View Slide

  60. goodapi.co
    COMPLEX API LANDSCAPE
    REST APIs

    View Slide

  61. goodapi.co
    CONCLUSION

    View Slide

  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

    View Slide

  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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

  67. PHOTOS BY UNSPLASH.COM

    View Slide

  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)

    View Slide

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

    View Slide

  70. goodapi.co

    View Slide

  71. goodapi.co

    View Slide

  72. goodapi.co

    View Slide

  73. goodapi.co
    ARCHITECTURAL PROPERTIES
    OF KEY INTEREST

    View Slide

  74. goodapi.co
    DISTRIBUTED SYSTEM PROPERTIES

    View Slide