REST Beyond the Obvious – API design for ever evolving systems

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

@springcentral

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
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 !
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
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 ?
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
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
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", … }
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", … }
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