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

Oliver Drotbohm

May 24, 2018
Tweet

More Decks by Oliver Drotbohm

Other Decks in Programming

Transcript

  1. API DESIGN FOR EVER EVOLVING SYSTEMS
    @odrotbohm
    Oliver Drotbohm ƀ [email protected]
    odrotbohm

    View Slide

  2. REST
    3

    View Slide

  3. ARCHITECTURAL
    CONSTRAINTS
    TRAITS
    5
    Evolvability, Scalability, Fault Tolerance, …
    Client-Server, Statelessness, Cacheability, Uniform Interface, Layered System, (Code on Demand…)

    View Slide

  4. CONSTRAINTS
    AS ENABLERS
    6

    View Slide

  5. EVOLVABILITY
    7

    View Slide

  6. 8

    View Slide

  7. 9

    View Slide

  8. -
    10

    View Slide

  9. 12
    CRUD +
    Validation
     Browser
    Ȑ Application
     Database
    {…}
    JS
    CRUD
    Business logic
    Validation

    View Slide

  10. ’ „ “
    13

    View Slide

  11. 14
     Browser
    Ȑ Application
     Database
    {…}
    JS
    Mobile
    {…}
    CRUD
    CRUD +
    Validation
    Business logic
    Validation

    View Slide

  12. ?
    15
    !

    View Slide

  13. ?
    16
    !

    View Slide

  14. ?
    17
    !

    View Slide

  15. 18

    View Slide

  16. 20

    View Slide

  17. 21
    From: Stefan Tilkov – Microservices: Patterns and Antipatterns
    Data CRUD via HTTP / JDBC in disguise

    View Slide

  18. 22
    From: Geek And Poke – Future-proof Your Data Model

    View Slide

  19. 23

    View Slide

  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

    View Slide

  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

    View Slide

  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

    View Slide

  23. 26
    Data
    Domain Logic
    Process Flow
    Presentation
    Clients
    Server
    &

    View Slide

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

    View Slide

  25. 29

    View Slide

  26. CONTRACTS
    30

    View Slide

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

    Salutation salutation;
    }
    enum Salutation { MR, MRS; }

    View Slide

  28. 32
    {
    "type": „object“,
    "properties": {
    "salutation": {
    "type": "array",
    "items": {
    "type": "string",
    "enum": ["Mr", "Mrs"]
    }
    }
    }
    }

    View Slide

  29. ?
    33
    !

    View Slide

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

    Salutation salutation;
    }
    enum Salutation { MR, MRS, PROF; }
    34

    View Slide

  31. {
    "type": "object",
    "properties": {
    "salutation": {
    "type": "array",
    "items": {
    "type": "string",
    "enum": ["Mr", "Mrs", "Prof"]
    }
    }
    }
    }
    36

    View Slide


  32. 37

    View Slide

  33. 38

    View Slide

  34. 39
    Jim Weirich, 2009 – Video @ YouTube
    The Grand Unified Theory
    Meilir Page-Jones, 2000 – Book @ Amazon
    Fundamentals of Object-oriented Design in UML

    View Slide

  35. 40
    From: Connascence – Wikipedia

    View Slide

  36. 41
    From: Connascence – Wikipedia

    View Slide






  37. 42

    View Slide

  38. VERSIONING
    43

    View Slide

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

    View Slide

  40. The Cost of Versioning an API
    45
    From: Jacques Dubray - Understanding the cost of versioning an API

    View Slide

  41. HYPERMEDIA
    46

    View Slide

  42. 47

    View Slide

  43. 48

    View Slide


  44. 49

    View Slide

  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

    View Slide

  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

    View Slide

  47. 52
    GET /order/4711
    {
    "createdDate" : …,
    "status" : "Payment expected"

    }

    View Slide

  48. ?
    53
    !

    View Slide

  49. 1
    54

    View Slide

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

    }

    View Slide

  51. 56

    View Slide

  52. AAARGH!
    57

    View Slide

  53. 2
    58

    View Slide

  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

    View Slide

  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

    View Slide

  56. 61
    GET /order/42
    {
    "_links" : {
    "cancel" : { "href" : … },
    }, …
    "createdDate" : …,
    "status" : "Payment expected",

    }

    View Slide

  57. 62

    View Slide

  58. 63

    View Slide

  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

    View Slide

  60. THANK YOU!
    65
    #
    @odrotbohm
    Oliver Drotbohm ƀ [email protected]
    odrotbohm

    View Slide

  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

    View Slide

  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

    View Slide