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

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