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

    rest
 beyond
 the
 obvious API design for ever evolving systems

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

    2

  3. 3.
  4. 4.

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

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

    9 CRUD + Validation  Browser Ȑ Application  Database

    {…} JS CRUD Business logic Validation
  6. 10.

    11  Browser Ȑ Application  Database {…} JS Mobile

    {…} CRUD CRUD + Validation Business logic Validation
  7. 14.

    the less your systems & teams have to talk to

    each other,
 the more independently they can evolve. 14
  8. 15.

    api evolvability
 is key in a system of systems. 15

    See „Evolving Distributed Systems“
  9. 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
  10. 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
  11. 29.

    28 Data Domain Logic Process Flow Presentation Clients Server business

    logic
 is replicated
 into and
 amongst
 clients which creates coupling
  12. 30.

    29 Data Domain Logic Process Flow Presentation Clients Server Clients

    Server what if we could prevent that leakage?
  13. 33.

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

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

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

    } class UserAccount(Info) {
 enum Salutation { MR, MRS; } private Salutation salutation; }
  15. 36.

    class SomeService { UserAccount create(UserAccountInfo info) { … } }

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

    35

  17. 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
  18. 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
  19. 40.

    " stronger forms of connascence are acceptable if the elements

    involved are closely related. 38 From: Connascence – Wikipedia
  20. 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
  21. 42.

    … of algorithm … of position … of meaning …

    of type … of name 40 connascence
  22. 43.

    … of algorithm … of position … of meaning …

    of type … of name 40 connascence
  23. 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 "
  24. 46.

    43

  25. 47.

    The Cost of Versioning an API 44 From: Jacques Dubray

    - Understanding the cost of versioning an API
  26. 48.

    45

  27. 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
  28. 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
  29. 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
  30. 64.

    61 GET /order/42 { „_links“ : { „cancel“ : {

    „href“ : … }, … „createdDate“ : …, „status“ : „Payment expected“ … }
  31. 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