REST Beyond the Obvious – API design for ever evolving systems

REST Beyond the Obvious – API design for ever evolving systems

Slides of the talk I held at Spring I/O 2018.

@springcentral

977c74bb044a9d4fa90b305824eda390?s=128

Oliver Drotbohm

May 24, 2018
Tweet

Transcript

  1. rest
 beyond
 the
 obvious API design for ever evolving systems

    / olivergierke Oliver Gierke ƀ ogierke@pivotal.io #springio18
  2. 2

  3. REST 3

  4. ARCHITECTURAL CONSTRAINTS TRAITS 4 Evolvability, Scalability, Fault Tolerance, … Client-Server,

    Statelessness, Cacheability, Uniform Interface, Layered System, (Code on Demand…)
  5. EVOLVABILITY 5

  6. 7 context abstraction coupling

  7. 8  Browser Ȑ Application  Database CRUD Business logic

  8. 9 CRUD + Validation  Browser Ȑ Application  Database

    {…} JS CRUD Business logic Validation
  9. you don’t „move“ business logic to
 the client,
 you replicate

    it into it. 10
  10. 11  Browser Ȑ Application  Database {…} JS Mobile

    {…} CRUD CRUD + Validation Business logic Validation
  11. frontend vs. backend
 services 12

  12. 13 Service {…} Service {…} Service {…}

  13. 13 Service {…} Service {…} Service {…} Service {…} Service

    {…} Service {…} Service {…}
  14. the less your systems & teams have to talk to

    each other,
 the more independently they can evolve. 14
  15. api evolvability
 is key in a system of systems. 15

    See „Evolving Distributed Systems“
  16. the
 client-server
 relationship 16

  17. are you
 in charge
 of the client? 17 !

  18. are you
 in charge
 of the
 client releases? 18 !

  19. are you
 in charge
 of the client deployments? 19 !

  20. do you
 know
 your clients? 20 !

  21. do you
 want to know
 your clients? 21 !

  22. 22 context abstraction coupling

  23. 23 From: Stefan Tilkov – Microservices: Patterns and Antipatterns Data

    Domain Logic Process Flow Presentation CRUD via HTTP / JDBC in disguise Spring Data REST / Re-usable, but low-level Useful and specific
  24. elevating an api abstraction level to http adds cost. 24

  25. what are the benefits you get for that cost? 25

    !
  26. ironically,
 the more generic your api,
 the more coupling you

    create. 26
  27. 27 Data Domain Logic Process Flow Presentation From: Stefan Tilkov

    – Microservices: Patterns and Antipatterns CRUD via HTTP / JDBC in disguise Spring Data REST / Re-usable, but low-level Useful and specific
  28. 28 Data Domain Logic Process Flow Presentation

  29. 28 Data Domain Logic Process Flow Presentation Clients Server business

    logic
 is replicated
 into and
 amongst
 clients which creates coupling
  30. 29 Data Domain Logic Process Flow Presentation Clients Server Clients

    Server what if we could prevent that leakage?
  31. 30 context abstraction coupling

  32. CONTRACTS 31

  33. 32 class SomeService { UserAccount create(UserAccountInfo info) { … }

    } class UserAccount(Info) {
 enum Salutation { MR, MRS; } private Salutation salutation; }
  34. what happens if we add a new enum value? 33

    !
  35. 34 class SomeService { UserAccount create(UserAccountInfo info) { … }

    } class UserAccount(Info) {
 enum Salutation { MR, MRS; } private Salutation salutation; }
  36. class SomeService { UserAccount create(UserAccountInfo info) { … } }

    class UserAccount(Info) {
 enum Salutation { MR, MRS, PROF; } private Salutation salutation; } 34
  37. 35

  38. connascence 36 Jim Weirich, 2009 – Video @ YouTube The

    Grand Unified Theory Meilir Page-Jones, 2000 – Book @ Amazon Fundamentals of Object-oriented Design in UML
  39. " in software engineering, two components are connascent if a

    change in one would require the other to be modified in order to maintain the overall correctness of the system. 37 From: Connascence – Wikipedia
  40. " stronger forms of connascence are acceptable if the elements

    involved are closely related. 38 From: Connascence – Wikipedia
  41. " the same strength and degree of connascence will have

    a higher difficulty and cost of change, the more distant the involved elements are. 39 From: Connascence – Wikipedia
  42. … of algorithm … of position … of meaning …

    of type … of name 40 connascence
  43. … of algorithm … of position … of meaning …

    of type … of name 40 connascence
  44. VERSIONING 41

  45. a programmer had a problem. they thought: 
 „i’ll just

    use versions!“
 
 now they had problem 1.0, problem 2.0, problem 2.1… 42 "
  46. 43

  47. The Cost of Versioning an API 44 From: Jacques Dubray

    - Understanding the cost of versioning an API
  48. 45

  49. HYPERMEDIA 46

  50. serving data
 and navigation information
 at the same time. 47

  51. hypermedia
 as the engine
 of application state 48

  52. serving links conditionally depending on the resource’s state. 49

  53. 50 payment expected preparing cancelled ready completed 1 2 3

    4 5 6 restbucks
  54. 51 Method URI Action Step POST /orders Create new order

    1 POST/PATCH /orders/{id} Update the order (only if "payment expected") 2 DELETE /orders/{id} Cancel order (only if "payment expected") 3 PUT /orders/{id}/payment Pay order (only if "payment expected") 4 Barista preparing the order GET /orders/{id} Poll order state 5 GET /orders/{id}/receipt Access receipt DELETE /orders/{id}/receipt Conclude the order process 6
  55. 52 GET /order/4711 { „createdDate“ : …, „status“ : „Payment

    expected“ … }
  56. how does the client know if a state transition is

    allowed? 53 !
  57. option 1:
 inspecting the payload 54

  58. 55 GET /order/4711 { „createdDate“ : …, „status“ : „Payment

    expected“ … }
  59. " internationalize
 all user facing text. 56

  60. AAARGH! 57

  61. option 2:
 inspecting
 hypermedia elements 58

  62. Method URI Action Step POST /orders Create new order 1

    POST/PATCH /orders/{id} Update the order (only if "payment expected") 2 DELETE /orders/{id} Cancel order (only if "payment expected") 3 PUT /orders/{id}/payment Pay order (only if "payment expected") 4 Barista preparing the order GET /orders/{id} Poll order state 5 GET /orders/{id}/receipt Access receipt DELETE /orders/{id}/receipt Conclude the order process 6 59
  63. 60 Method Resource type Action Step POST orders Create new

    order 1 POST/PATCH update Update the order 2 DELETE cancel Cancel order 3 PUT payment Pay order 4 Barista preparing the order GET order Poll order state 5 GET receipt Access receipt DELETE receipt Conclude the order process 6
  64. 61 GET /order/42 { „_links“ : { „cancel“ : {

    „href“ : … }, … „createdDate“ : …, „status“ : „Payment expected“ … }
  65. simplifying decisions in clients to whether a link is present

    or not. 62
  66. trading domain knowledge
 with protocol complexity in clients. 63

  67. 64 Amount of domain knowledge in the client Amount of

    protocol knowledge in the client Coupling to the server Non-hypermedia
 based systems Hypermedia
 based systems
  68. THE
 SPRING
 ECOSYSTEM 65 #

  69. spring hateoas 66 Bread and butter hypermedia support
 (mostly HAL,

    more coming)
  70. spring restdocs 67 Test-driven API documentation

  71. spring
 cloud contract 68 (Consumer-Driven) Contract testing
 Generation of client

    & server stubs
  72. SUMMARY 69

  73. high-level apis
 
 over
 
 crud ones that
 replicate business


    logic into clients 70
  74. hypermedia
 and late binding 
 
 over
 
 hard-coded uris


    and interactions 71
  75. protocol
 knowledge 
 over
 
 domain
 knowledge 72

  76. test-verified
 documentation 
 over
 
 docs derived from
 static code

    analysis 73
  77. embedded api
 docs and specs 
 over
 
 a separate


    developer portal 74
  78. THANK YOU! 75 / olivergierke Oliver Gierke ƀ ogierke@pivotal.io $

    #springio18