Upgrade to Pro — share decks privately, control downloads, hide ads and more …

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. API DESIGN FOR EVER EVOLVING SYSTEMS @odrotbohm Oliver Drotbohm ƀ

    odrotbohm@pivotal.io odrotbohm
  2. REST 3

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

    Statelessness, Cacheability, Uniform Interface, Layered System, (Code on Demand…)
  4. CONSTRAINTS AS ENABLERS 6

  5. EVOLVABILITY 7

  6. 8

  7. 9

  8. - 10

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

    {…} JS CRUD Business logic Validation
  10. ’ „ “ 13

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

    {…} CRUD CRUD + Validation Business logic Validation
  12. ? 15 !

  13. ? 16 !

  14. ? 17 !

  15. 18

  16. 20

  17. 21 From: Stefan Tilkov – Microservices: Patterns and Antipatterns Data

    CRUD via HTTP / JDBC in disguise
  18. 22 From: Geek And Poke – Future-proof Your Data Model

  19. 23

  20. 24 From: Stefan Tilkov – Microservices: Patterns and Antipatterns Data

    Domain Logic CRUD via HTTP / JDBC in disguise Spring Data REST / Re-usable, but low-level
  21. 24 From: Stefan Tilkov – Microservices: Patterns and Antipatterns Data

    Domain Logic Process Flow CRUD via HTTP / JDBC in disguise Spring Data REST / Re-usable, but low-level Useful and specific
  22. 25 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
  23. 26 Data Domain Logic Process Flow Presentation Clients Server &

  24. 27 Data Domain Logic Process Flow Presentation Clients Server Clients

    Server ?
  25. 29

  26. CONTRACTS 30

  27. 31 class SomeService { UserAccount create(…) { … } }

    class UserAccount {
 Salutation salutation; } enum Salutation { MR, MRS; }
  28. 32 { "type": „object“, "properties": { "salutation": { "type": "array",

    "items": { "type": "string", "enum": ["Mr", "Mrs"] } } } }
  29. ? 33 !

  30. class SomeService { UserAccount create(…) { … } } class

    UserAccount {
 Salutation salutation; } enum Salutation { MR, MRS, PROF; } 34
  31. { "type": "object", "properties": { "salutation": { "type": "array", "items":

    { "type": "string", "enum": ["Mr", "Mrs", "Prof"] } } } } 36
  32. ’ 37

  33. 38

  34. 39 Jim Weirich, 2009 – Video @ YouTube The Grand

    Unified Theory Meilir Page-Jones, 2000 – Book @ Amazon Fundamentals of Object-oriented Design in UML
  35. 40 From: Connascence – Wikipedia

  36. 41 From: Connascence – Wikipedia

  37. … … … … … 42

  38. VERSIONING 43

  39. „ ’ !“ 1 0 2 0 2 1… 44

    "
  40. The Cost of Versioning an API 45 From: Jacques Dubray

    - Understanding the cost of versioning an API
  41. HYPERMEDIA 46

  42. 47

  43. 48

  44. ’ 49

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

    4 5 6 From: REST In Practice – O'Reilly Sample code @ GitHub: Spring RESTBucks
  46. 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
  47. 52 GET /order/4711 { "createdDate" : …, "status" : "Payment

    expected" … }
  48. ? 53 !

  49. 1 54

  50. 55 GET /order/4711 { "createdDate" : …, "status" : "Payment

    expected", … }
  51. 56

  52. AAARGH! 57

  53. 2 58

  54. 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
  55. 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
  56. 61 GET /order/42 { "_links" : { "cancel" : {

    "href" : … }, }, … "createdDate" : …, "status" : "Payment expected", … }
  57. 62

  58. 63

  59. 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
  60. THANK YOU! 65 # @odrotbohm Oliver Drotbohm ƀ odrotbohm@pivotal.io odrotbohm

  61. 66 Architectural Styles and the Design of Network-based Software Architectures

    Fielding – Dissertation PDF Evolving Distributed Systems Gierke – Blog Microservices: Patterns and Antipatterns Tilkov – Slide deck @ Speakerdeck Fundamentals of Object-oriented Design in UML Meilir Page-Jones, 2000 – Book @ Amazon The Grand Unified Theory Jim Weirich, 2009 – Video @ YouTube
  62. REST In Practice Parastatidis, Webber, Robinson – Book @ O'Reilly

    Spring RESTBucks Drotbohm – Code @ GitHub Spring HATEOAS Project website Spring REST Docs Project website Spring Cloud Contract Project website 67