HATEOAS dla ludzi!

W swojej prezentacji opowiem o dziwnym stworzeniu, które nazywa się HATEOAS i jest częstym tematem prezentacji, jednak w praktyce widuje się je znacznie rzadziej. Postaram się podzielić doświadczeniami z moich poprzednich projektów, gdzie miałem okazję implementować i konsumować API z HATEOASem. Opowiem, dlaczego warto i dlaczego czasem jednak nie warto, jakie wyzwania stawia(ł) przed nami HATEOAS oraz jak dzięki niemu zmieniło się moje patrzenie na oprogramowanie. Postaram się pokazać praktyczne przykłady.

Transcript

1. HATEOAS dla ludzi! Mateusz Stasch
2. Mateusz Stasch @mattstasch | https://mattstasch.net
3. Pytania?
4. AHA! Moment
5. HATEOAS
6. Hypermedia As The Engine Of Application State
7. Wikipedia
8. Wikipedia ORP Kom. Piłsudzki Barycz (Wyszanów) Antylopowiec modry Deklaracja niepodległości
9. Wikipedia ORP Kom. Piłsudzki Barycz (Wyszanów) Antylopowiec modry Deklaracja niepodległości Polska Odra Sułów Wdrażanie Ramowej Dyrektywy Wodnej w zlewni Baryczy
10. Wikipedia ORP Kom. Piłsudzki Barycz (Wyszanów) Antylopowiec modry Deklaracja niepodległości Polska Odra Sułów Wdrażanie Ramowej Dyrektywy Wodnej w zlewni Baryczy Mieszko I Józef Stalin Andrzej Duda
11. Wikipedia ORP Kom. Piłsudzki Barycz (Wyszanów) Antylopowiec modry Deklaracja niepodległości Polska Odra Sułów Wdrażanie Ramowej Dyrektywy Wodnej w zlewni Baryczy Mieszko I Józef Stalin Andrzej Duda
12. GET /notes/3381 HTTP/1.1 Host: api.service.com Authorization: bearer <token> --- { data: {...}, links: [ { "rel": "self", "href": "https://api.service.com/note/3381", "method": "GET" }, { "rel": "followers", "href": "https://api.service.com/note/3381/followers", "method": "GET" }, ... ] }
13. GET /notes/3381 HTTP/1.1 Host: api.service.com Authorization: bearer <token> --- { data: {...}, links: [ { "rel": "self", "href": "https://api.service.com/notes/3381", "method": "GET" }, { "rel": "follow", "href": "https://api.service.com/notes/3381/followers", "method": "POST" }, ... ] }
14. GET /notes/3381 HTTP/1.1 Host: api.service.com Authorization: bearer <token> --- { data: {...}, links: [ { "rel": "self", "href": "https://api.service.com/notes/3381", "method": "GET" }, { "rel": "follow", "href": "https://api.service.com/notes/3381/followers", "method": "POST" }, ... ] }
15. REST
17. Richardson Maturity Model
18. REST != HTTP + JSON
19. REST !== HTTP + JSON
20. Code On-Demand Client-Server Separation Stateless Communication Uniform Interface Layered System Explicit Caching
21. Code On-Demand Client-Server Separation Stateless Communication Layered System Explicit Caching URIs + HATEOAS + Self Descriptive + …
22. REST !== HTTP + JSON
23. REST + HTTP + JSON
24. GET /notes/3381 HTTP/1.1 Host: api.service.com Authorization: bearer <token> --- { data: {...}, links: [ { "rel": "self", "href": "https://api.service.com/notes/3381", "method": "GET" }, { "rel": "follow", "href": "https://api.service.com/notes/3381/followers", "method": "POST" }, ... ] }
25. namespace My.Service.REST { public class Hypermedia { public Hypermedia(string rel, string method, string href) { ... } public string Rel { get; private set; } public string Method { get; private set; } public string Href { get; private set; } } public class Resource : IResource { protected Resource() { Links = new Dictionary<string, Hypermedia>(); } public IDictionary<string, Hypermedia> Links { get; set; } } }
26. namespace My.Service.REST { public class Resources<T> : Resource, ICollectionOfResources<T> where T: IResource { protected Resources(IEnumerable<T> members) { Members = new ReadOnlyCollection(members) } public ReadOnlyCollection<T> Members { get; set; } } }
27. namespace My.Service.Controllers { public class NotesController { … public Notes Get(NoteId id) { var note = GetNoteById(id) .WrapInResource() .Link("self", _ => _.Get(id)) .Link("follow", _ => _.Follow(id)) … return note; } } }
29. HTTP 1.1 POST /my/own/resource Host: example.org Authorization: Bearer <token> … /my /own /resource HTTP/1.1 200 OK ETag: "4ab4bec9811" Location: ???
30. Relative to Service: resource/123
31. Relative to Service: resource/123 Relative to Root: /my/own/resource/123
32. Absolute: https://example.org/my/own/resource/123 Relative to Service: resource/123 Relative to Root: /my/own/resource/123
33. Absolute: https://example.org/my/own/resource/123 Relative to Service: resource/123 Relative to Root: /my/own/resource/123
34. Gdzie jest moja usługa?!
35. HTTP 1.1 POST /my/own/resource Host: example.org Authorization: Bearer <token> … /my /own /resource HTTP/1.1 200 OK ETag: "4ab4bec9811" Location: /my/own/resource/123
36. HTTP 1.1 POST /my/own/resource Host: example.org Authorization: Bearer <token> … /my /own /resource HTTP/1.1 200 OK ETag: "4ab4bec9811" Location: /my/own/resource/123 "basePath": "/my/own/"
37. HTTP 1.1 POST /my/own/resource Host: example.org Authorization: Bearer <token> … /my /own /resource HTTP/1.1 200 OK ETag: "4ab4bec9811" Location: /my/own/resource/123 X-Forwarded-BasePath: /my X-Forwarded-BasePath: {$X_Forwarded_BasePath}/own
38. HTTP 1.1 POST /my/own/resource Host: example.org Authorization: Bearer <token> … /my /own /resource HTTP/1.1 200 OK ETag: "4ab4bec9811" Location: /my/own/resource/123 X-Forwarded-BasePath: /my X-Forwarded-BasePath: {$X_Forwarded_BasePath}/own
39. HTTP 1.1 POST /my/own/resource Host: example.org Authorization: Bearer <token> … /my /own /resource HTTP/1.1 200 OK ETag: "4ab4bec9811" Location: /my/own/resource/123 X-Forwarded-BasePath: /my X-Forwarded-BasePath: {$X_Forwarded_BasePath}/own
40. State User Context Hypermedia
41. GET /notes/3381/followers HTTP/1.1 Host: api.service.com Authorization: bearer <token> --- { data: {...}, links: [ { "rel": "self", "href": "https://api.service.com/notes/3381/followers", "method": "GET" }, { "rel": "add", "href": "https://api.service.com/notes/3381/followers", "method": "POST" }, ... ] }
42. GET /notes/3381/followers HTTP/1.1 Host: api.service.com Authorization: bearer <token> --- { data: {...}, links: [ { "rel": "self", "href": "https://api.service.com/notes/3381/followers", "method": "GET" }, { "rel": "add", "href": "https://api.service.com/notes/3381/followers", "method": "POST" }, ... ] }
43. Jak drogie jest ustalenie stanu?
44. Note (3381) Open, U1 Open Close Assign Hypermedia
45. WRITE Model READ Model READ Model READ Model DTO Input Model Platoński interfejs WSP
46. Co można z tym zrobić?
48. <Button action={notesService.deleteNote} enabled={!note.isDeleted && note.isInStatus(Open, Declined, Unass && this.user.isInRole(Manager) && isAirConditioningOn} >Delete</Button>
49. <Button action={notesService.deleteNote} enabled={!note.isDeleted && note.isInStatus(Open, Declined, Unass && this.user.isInRole(Manager) && isAirConditioningOn && random() !== 4}>Delete</Button> Obrazek: Refactoring.Guru
50. { title: "Skończyła się kawa w kuchni na parterze", status: "Open", links: [ { "rel": "self", "href": "https://api.service.com/notes/3381", "method": "GET" }, { "rel": "delete", "href": "https://api.service.com/notes/3381 ", "method": "DELETE" }, ... ] }
51. <Button action={note.getAction("delete")} enabled={note.hasLink("delete")} >Delete</Button>
52. <Button action={note.getAction("delete")} >Delete</Button>
53. Jedno źródło prawdy o stanie system Prostsza implementacja klientów
54. Crawler + Decoupling using 302
56. { members: […] _links: [ { "rel": "self", "href": "https://api.service.com/notes?after=3381", "method": "GET" }, { "rel": "next", "href": "https://api.service.com/notes?after=3421", "method": "GET" }, … ] }
57. { members: […] _links: [ { "rel": "self", "href": "https://api.service.com/notes?after=3381", "method": "GET" }, { "rel": "next", "href": "https://api.service.com/notes?after=3421", "method": "GET" }, … ] } Go to next page… Process my items
58. { members: […] _links: [ { "rel": "self", "href": "https://api.service.com/notes?after=3381", "method": "GET" }, { "rel": "next", "href": "https://api.service.com/notes?after=3421", "method": "GET" }, … ] } Iterator IProcessor
59. Decoupling nawigacji od danych Segregacja interfejsów Prostsza implementacja klientów
60. HATEOAS + Explicit Caching =
61. Code On-Demand Client-Server Separation Stateless Communication Uniform Interface Layered System Explicit Caching
62. HTTP/1.1 GET /my/own/resource/123 Host: example.org If-None-Match: "4ab4bec9811" Authorization: Bearer <token> HTTP/1.1 200 OK ETag: "4ab4bec9811" … API
63. HTTP 1.1 GET /my/own/resource/123 Host: example.org If-None-Match: "4ab4bec9811" Authorization: Bearer <token> /my /own /resource HTTP/1.1 304 Not Modified ETag: "4ab4bec9811"
64. HTTP 1.1 GET /my/own/resource/123 Host: example.org If-None-Match: "4ab4bec9811" Authorization: Bearer <token> /my /own /resource HTTP/1.1 200 OK ETag: "4ab4bec9811" …
65. HTTP 1.1 GET /my/own/resource/123 Host: example.org If-None-Match: "4ab4bec9811" Authorization: Bearer <token> /my /own /resource HTTP/1.1 200 OK ETag: "4ab4bec9811" … Cache
66. Brak wsparcia! Uproszczenia, sztywne frameworki, życzeniowe myślenie
67. namespace My.Service.REST { public class Hypermedia { public Hypermedia(string rel, string method, string href) { ... } public string Rel { get; private set; } public string Method { get; private set; } public string Href { get; private set; } } public class Resource : IResource { protected Resource() { Links = new Dictionary<string, Hypermedia>(); } public IDictionary<string, Hypermedia> Links { get; set; } } }
68. HAL
69. HAL
70. TAK
71. TAK
72. TAK
73. TAK SRP
74. TAK SRP
75. TAK SRP Decoupling
76. NIE
77. NIE
78. NIE
79. NIE
80. NIE
81. NIE
82. HATEOAS dla ludzi! Mateusz Stasch The End!
83. Q & A Mateusz Stasch
84. • https://mattstasch.net/2017/09/HATEOAS-introduction • https://mattstasch.net/2017/11/HATEOAS-in-WebAPI2 • https://martinfowler.com/articles/richardsonMaturityModel.html • http://stateless.co/hal_specification.html • http://jsonapi.org