GraphQL, gRPC or REST? Resolving the API Developer's Dilemma

GraphQL, gRPC, REST and WebHooks are among a bewildering array of technologies and architectural styles that are available to API developers today. Presented with such myriad options, how can we be confident of making an appropriate decision for the problem at hand? In search of guidance, developers often turn to online communities. This can exacerbate the problem as discussions about API styles often descend into statements about the superiority of one approach over another being presented as universal truths. Such comments invariably earn emotive rebuttals that also lack sufficient nuance. The result of such exchanges is increased confusion and uncertainty. Join me on a tour of these API styles where we will cut through this noise, demonstrate where each style shines (plus where they don't!) and ultimately resolve this dilemma of choice.

In this session we'll take an in-depth look at API design; the best practices that have evolved; the game changing supporting technologies that are now available including HTTP/2; and most importantly what you need to do to deliver a world class developer experience:

- How to determine the suitability of an API style for your application context. Don't be a victim of technology hype!
- What is required to support graceful evolution of the API contract including the potential implications of both Hyrum's Law and the Law of Implicit Interfaces
- Understand the supporting toolchains and technologies that dovetail with each API style.
- The importance of treating your API as a product with an unwavering focus on improving the ease of consumption for your clients.

By the end of the session, you will not only understand the concepts underpinning these various API styles but also have the knowledge to put them into practice. If you want to take to your API design expertise to the next level,

Transcript

1. RESOLVING THE API DEVELOPER’S DILEMMA
   @ROBDCROWLEY | ROBDCROWLEY
   

   View Slide

2. ▪ A TOUR OF API STYLES OVER TIME
   ▪ CONSTRAINTS AND INDUCED PROPERTIES
   ▪ MYTH BUSTING
   ▪ SAMPLE SCENARIOS
   

   View Slide

3. View Slide

4. View Slide

5. View Slide

6. View Slide

7. View Slide

8. View Slide

9. ’
   

   View Slide

10. View Slide

11. View Slide

12. View Slide

13. View Slide

14. View Slide

15. ’
    

    View Slide

16. View Slide

17. View Slide

18. ’
    ’
    

    View Slide

19. ’
    

    View Slide

20. View Slide

21. View Slide

22. View Slide

23. View Slide

24. View Slide

25. Properties are induced by the set of
    constraints within an architecture
    

    View Slide

26. CUSTOMER / BUSINESS / PRODUCT REQUIREMENTS
    

    View Slide

27. IMPLICATIONS OF DISTRIBUTED SYSTEM COMPLEXITY, 8 FALLACIES,
    EVOLUTIONARY REQUIREMENTS
    

    View Slide

28. SYSTEM OF WORK, CONWAY’S LAW, KNOWLEDGE / EXPERTISE
    

    View Slide

29. ⇒
    

    View Slide

30. View Slide

31. “ ”
    

    View Slide

32. ’
    

    View Slide

33. “
    ”
    

    View Slide

34. “
    ”
    

    View Slide

35. View Slide

36. View Slide

37. View Slide

38. View Slide

39. ’
    

    View Slide

40. If an API is mostly actions, maybe it
    should be RPC. If an API is mostly CRUD
    and is manipulating related data, maybe
    it should be REST
    

    View Slide

41. View Slide

42. ▪ API STYLES ADDRESS DIFFERENT PROBLEM SPACES
    ▪ RESTISH APIS WOULD MOST LIKELY BE BETTER AS GRAPHQL OR RPC
    ▪ gRPC IS PERFECT FOR SYCHRONOUS COMMUNICATIONS BETWEEN
    INTERNAL SERVICES
    

    View Slide

43. “ “
    

    View Slide

44. View Slide

45. View Slide

46. View Slide

47. View Slide

48. View Slide

49. View Slide

50. View Slide

51. View Slide

52. ▪ THERE ARE MANY KINDS OF CACHES: CLIENT, SEVER AND NETWORK
    ▪ HIGHLY CUSTOMIZABLE APIS BENEFIT LESS FROM HTTP CACHING
    ▪ IF NETWORK CACHING IS VALUABLE THEN CONSIDER REST
    ▪ BEST PRACTICES ARE STILL EMERGING FOR GRAPHQL AND gRPC
    

    View Slide

53. “ “
    

    View Slide

54. ⇒
    

    View Slide

55. View Slide

56. GRAPHQL ENABLES EACH CLIENT TO RETRIEVE EXACTLY THE DATA IT
    REQUIRES IN A SINGLE ROUND TRIP TO THE SERVER
    

    View Slide

57. View Slide

58. View Slide

59. View Slide

60. View Slide

61. View Slide

62. ▪ WITH HTTP/1.X THE COST OF A HANDSHAKE WAS HIGH
    ▪ HTTP/2 REMOVES THE NEED FOR COMPOUND DOCUMENTS
    ▪ SERVER PUSH CREATES NEW POSSIBILITIES BUT PROFILE USE
    CASES THOROUGHLY
    

    View Slide

63. “
    “
    

    View Slide

64. View Slide

65. View Slide

66. View Slide

67. ▪ DON’T ADD REQUIRED INPUTS
    ▪ DON’T REMOVE OUTPUTS OR MAKE THEM OPTIONAL
    ▪ DON’T CHANGE THE TYPE OF A FIELD
    ▪ FOLLOW THE ROBUSTNESS PRINCIPLE / POSTEL’S LAW
    

    View Slide

68. View Slide

69. View Slide

70. View Slide

71. With a sufficient number of users of
    an API, it does not matter what you
    promise in the contract: all observable
    behaviours of your system will be
    depended on by somebody.
    ’
    

    View Slide

72. View Slide

73. Make a system evolvable by paying
    attention to the interfaces.
    

    View Slide

74. View Slide

75. - Front end and back end teams
    agree on schema.
    - UI is developed using mocked data
    based on schema
    - API is built out with any changes
    being communicated to front end
    team
    - Integrate front and back ends
    - Ship
    - Repeat
    

    View Slide

76. ▪ IS A TECHNIQUE TO MANAGE BREAKING CHANGES
    ▪ SHOULD BE A LAST RESORT, PREFER GRACEFUL EVOLUTION
    ▪ IS NOT A SUBSTITUTE FOR COMMUNICATING WITH USERS
    ▪ DOES NOT PROTECT AGAINST CONSUMERS DEPENDING ON
    IMPLICIT INTERFACE BEHAVIOUR
    

    View Slide

77. “
    “
    

    View Slide

78. View Slide

79. View Slide

80. View Slide

81. ▪ API DESIGN SKILLS ARE TABLE STAKES IRRESPECTIVE OF STYLE
    ▪ DESIGING A REST API FOLLOWS OUTSIDE-IN FLOW
    ▪ GRAPHQL DELAYS THIS MOMENT TO PROFILING QUERIES
    

    View Slide

82. View Slide

83. CRUD. SINGLE CLIENT THAT USES ALL FIELDS. USE CASE THAT IS WELL
    SUITED TO REST.
    

    View Slide

84. AGGREGATE DATA FROM MULTIPLE SOURCES INTO ONE CONVENIENT
    API. PERFECT USE CASE FOR GRAPHQL.
    

    View Slide

85. View Slide

86. SINGLE CLIENT. API IS STATIC AND WELL UNDERSTOOD. USE CASE WELL
    SUITED TO GRPC (I’M STILL EXPERIMENTING THOUGH!)
    

    View Slide

87. View Slide

88. POLYGLOT ENVIRONMENT. GRPC IS PERFECT FOR SYCHRONOUS
    COMMUNICATION BETWEEN INTERNAL MICROSERVICES.
    

    View Slide

89. View Slide

90. View Slide

91. View Slide

92. View Slide

93. View Slide

94. ▪
    ▪
    ▪
    ▪
    ▪
    ▪
    ▪
    ▪
    

    View Slide

95. ▪
    ▪
    ▪
    

    View Slide

96. ▪
    ▪
    ▪
    ▪
    ▪
    ▪
    ▪
    

    View Slide