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.

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

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

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.cogoodapi.co
API PARADIGMS
API ARCHITECTURAL
STYLES

21. goodapi.co
API PARADIGMS
Web APIs
Query APIs Streaming APIs
RPC APIsFlat 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.cogoodapi.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
@zdneFull 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 ifRules 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 ifRules 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