Slide 1
Slide 1 text
API DESIGN FOR EVER EVOLVING SYSTEMS
@odrotbohm
Oliver Drotbohm ƀ [email protected]
odrotbohm
Slide 2
Slide 2 text
REST
3
Slide 3
Slide 3 text
ARCHITECTURAL
CONSTRAINTS
TRAITS
5
Evolvability, Scalability, Fault Tolerance, …
Client-Server, Statelessness, Cacheability, Uniform Interface, Layered System, (Code on Demand…)
Slide 4
Slide 4 text
CONSTRAINTS
AS ENABLERS
6
Slide 5
Slide 5 text
EVOLVABILITY
7
Slide 6
Slide 6 text
8
Slide 7
Slide 7 text
9
Slide 8
Slide 8 text
-
10
Slide 9
Slide 9 text
12
CRUD +
Validation
Browser
Ȑ Application
Database
{…}
JS
CRUD
Business logic
Validation
Slide 10
Slide 10 text
’ „ “
13
Slide 11
Slide 11 text
14
Browser
Ȑ Application
Database
{…}
JS
Mobile
{…}
CRUD
CRUD +
Validation
Business logic
Validation
Slide 12
Slide 12 text
?
15
!
Slide 13
Slide 13 text
?
16
!
Slide 14
Slide 14 text
?
17
!
Slide 15
Slide 15 text
18
Slide 16
Slide 16 text
20
Slide 17
Slide 17 text
21
From: Stefan Tilkov – Microservices: Patterns and Antipatterns
Data CRUD via HTTP / JDBC in disguise
Slide 18
Slide 18 text
22
From: Geek And Poke – Future-proof Your Data Model
Slide 19
Slide 19 text
23
Slide 20
Slide 20 text
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
Slide 21
Slide 21 text
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
Slide 22
Slide 22 text
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
Slide 23
Slide 23 text
26
Data
Domain Logic
Process Flow
Presentation
Clients
Server
&
Slide 24
Slide 24 text
27
Data
Domain Logic
Process Flow
Presentation
Clients
Server
Clients
Server
?
Slide 25
Slide 25 text
29
Slide 26
Slide 26 text
CONTRACTS
30
Slide 27
Slide 27 text
31
class SomeService {
UserAccount create(…) { … }
}
class UserAccount {
Salutation salutation;
}
enum Salutation { MR, MRS; }
Slide 28
Slide 28 text
32
{
"type": „object“,
"properties": {
"salutation": {
"type": "array",
"items": {
"type": "string",
"enum": ["Mr", "Mrs"]
}
}
}
}
Slide 29
Slide 29 text
?
33
!
Slide 30
Slide 30 text
class SomeService {
UserAccount create(…) { … }
}
class UserAccount {
Salutation salutation;
}
enum Salutation { MR, MRS, PROF; }
34
Slide 31
Slide 31 text
{
"type": "object",
"properties": {
"salutation": {
"type": "array",
"items": {
"type": "string",
"enum": ["Mr", "Mrs", "Prof"]
}
}
}
}
36
Slide 32
Slide 32 text
’
37
Slide 33
Slide 33 text
38
Slide 34
Slide 34 text
39
Jim Weirich, 2009 – Video @ YouTube
The Grand Unified Theory
Meilir Page-Jones, 2000 – Book @ Amazon
Fundamentals of Object-oriented Design in UML
Slide 35
Slide 35 text
40
From: Connascence – Wikipedia
Slide 36
Slide 36 text
41
From: Connascence – Wikipedia
Slide 37
Slide 37 text
…
…
…
…
…
42
Slide 38
Slide 38 text
VERSIONING
43
Slide 39
Slide 39 text
„ ’ !“
1 0
2 0 2 1…
44
"
Slide 40
Slide 40 text
The Cost of Versioning an API
45
From: Jacques Dubray - Understanding the cost of versioning an API
Slide 41
Slide 41 text
HYPERMEDIA
46
Slide 42
Slide 42 text
47
Slide 43
Slide 43 text
48
Slide 44
Slide 44 text
’
49
Slide 45
Slide 45 text
50
payment
expected
preparing
cancelled
ready completed
1
2
3
4
5 6
From: REST In Practice – O'Reilly
Sample code @ GitHub: Spring RESTBucks
Slide 46
Slide 46 text
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
Slide 47
Slide 47 text
52
GET /order/4711
{
"createdDate" : …,
"status" : "Payment expected"
…
}
Slide 48
Slide 48 text
?
53
!
Slide 49
Slide 49 text
1
54
Slide 50
Slide 50 text
55
GET /order/4711
{
"createdDate" : …,
"status" : "Payment expected",
…
}
Slide 51
Slide 51 text
56
Slide 52
Slide 52 text
AAARGH!
57
Slide 53
Slide 53 text
2
58
Slide 54
Slide 54 text
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
Slide 55
Slide 55 text
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
Slide 56
Slide 56 text
61
GET /order/42
{
"_links" : {
"cancel" : { "href" : … },
}, …
"createdDate" : …,
"status" : "Payment expected",
…
}
Slide 57
Slide 57 text
62
Slide 58
Slide 58 text
63
Slide 59
Slide 59 text
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
Slide 61
Slide 61 text
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
Slide 62
Slide 62 text
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