Web service APIs are everywhere. In this talk we will show different visualizations obtained from a collection of real-world APIs, highlighting some design primitives, patterns and anti-patterns for API structures. We will also take the audience on a tour of how API evolve over the years and how the relationship between APIs and the Web continues to change over the decades.
2. Contents
• Motivating Example
• Interfaces vs. APIs
• API Tree Structures
• API Tree Structure Evolution
• API Evolution Tree Rings
• Web and APIs
3. Abstract
Web service APIs are everywhere. In this talk we will show different
visualizations obtained from a collection of real-world APIs,
highlighting some design primitives, patterns and anti-patterns for
API structures. We will also take the audience on a tour of how API
evolve over the years and how the relationship between APIs and
the Web continues to change over the decades.
6. Gas Station EV Charge Station
Scan credit card
Fill up tank
Get receipt
Scan customer
loyalty card
Register customer
info
Register payment
details
wait
Receive network id
card
Connect car to plug
(?)
Scan network id card
Charge
wait some more
14. API Technology
• Local / Remote Deployment
• Programming Language Speci c / Independent
• XML / JSON / String Payloads
• Formal / Informal Description
15. API Technology
• Local / Remote Deployment
• Programming Language Speci c / Independent
• XML / JSON / String Payloads
• Formal / Informal Description
32. G
GE
ET
T /users
/users
2
20
04
4 N
No
o C
Co
on
nt
te
en
nt
t
POST /users
POST /users
201 Created
201 Created
Location: /users/{id}
Location: /users/{id}
G
GE
ET
T /users/{id}
/users/{id}
2
200 OK
00 OK
PUT /users/{id}
PUT /users/{id}
200 OK
200 OK
DELETE /users/{id}
DELETE /users/{id}
200 OK
200 OK
Collection Conversation
70. Ingenico Server
Each line represents
an operation.
Its color corresponds
to the HTTP method.
5 days
Age
36
Paths
16
Commits
71. Multicolored lines
represent paths that
provide multiple
operations with
different HTTP
methods.
Operations are not
always added to a
path at the same
time.
72. Harbor API
Multicolored lines
represent paths that
provide multiple
operations with
different HTTP
methods.
Operations are not
always added to a
path at the same
time.
3 months 14 days
Age
19
Paths
50
Commits
73. Time ows outwards.
The oldest API
structures are shown
around the center.
The latest version is
on the outer ring.
74. eCards API
Time ows outwards.
The oldest API
structures are shown
around the center.
The latest version is
on the outer ring.
1 month 13 days
Age
21
Paths
38
Commits
75. This API was born as a
read-only API and
later acquired some
POST endpoints.
We can also spot a
rare transition from
GET to POST on the
same endpoint.
76. CarService API
This API was born as a
read-only API and
later acquired some
POST endpoints.
We can also spot a
rare transition from
GET to POST on the
same endpoint.
1 month 26 days
Age
49
Paths
95
Commits
78. OpenTrials API
The circular rings
represent time
intervals.
This read-only API is
more than one year
old.
1 year 2 months 16 days
Age
24
Paths
102
Commits
79. The distance between
the circular rings is
proportional to how
many commits have
been pushed within
the 6 months interval.
This 3.5 year old API
underwent a lot of
changes in the rst 6
months and almost
stabilized afterwards.
80. Flat API
The distance between
the circular rings is
proportional to how
many commits have
been pushed within
the 6 months interval.
This 3.5 year old API
underwent a lot of
changes in the rst 6
months and almost
stabilized afterwards.
3 years 10 months 16 days
Age
51
Paths
37
Commits
81. This API is less than
one year old, but it
did already undergo a
radical change once,
when most of its old
paths have been
pruned.
82. OpenPAI RESTful API
This API is less than
one year old, but it
did already undergo a
radical change once,
when most of its old
paths have been
pruned.
11 months 13 days
Age
73
Paths
36
Commits
83. If the previous API
changed radically
once, this one
underwent such
transitions regularly.
We can spot at least
three bundles of
paths that have been
replaced together
every six months or
so.
84. Clamp Rest API
If the previous API
changed radically
once, this one
underwent such
transitions regularly.
We can spot at least
three bundles of
paths that have been
replaced together
every six months or
so.
2 years 7 months 24 days
Age
90
Paths
33
Commits
85. Welcome to the CRUD
style API, with
endpoints providing
four operations (GET,
DELETE, PUT and
PATCH).
86. ID Vault
Welcome to the CRUD
style API, with
endpoints providing
four operations (GET,
DELETE, PUT and
PATCH).
1 month 27 days
Age
22
Paths
86
Commits
87. Here is another one,
with half CRUD
endpoints and half
read-only.
This is also an API
that has been growing
for almost four years
by always adding
more paths along the
way.
88. Apacta
Here is another one,
with half CRUD
endpoints and half
read-only.
This is also an API
that has been growing
for almost four years
by always adding
more paths along the
way.
3 years 11 months 12 days
Age
81
Paths
28
Commits
89. The designers of this
API have been
experimenting with
many different styles
over its 2 years of
existence.
Some experiments
were short lived,
while others
withstood the test of
time.
90. LibOpenStorage
The designers of this
API have been
experimenting with
many different styles
over its 2 years of
existence.
Some experiments
were short lived,
while others
withstood the test of
time.
2 years 19 days
Age
105
Paths
48
Commits
91. Here we can see that
only one path
introduced with the
rst release has
survived until the
current version.
Most of the current
paths are new, and
most of the original
ones have been
removed.
92. BMInventory
Here we can see that
only one path
introduced with the
rst release has
survived until the
current version.
Most of the current
paths are new, and
most of the original
ones have been
removed.
5 months 4 days
Age
56
Paths
132
Commits
93. Here we see a clear
case of API designers
lacking some colors in
their palette.
For some reason,
clients can only GET,
POST and DELETE.
94. MADApp API
Here we see a clear
case of API designers
lacking some colors in
their palette.
For some reason,
clients can only GET,
POST and DELETE.
3 years 1 month 21 days
Age
90
Paths
75
Commits
96. OpenStorage SDK
This 2.5-years-old API
was born as a Remote
Procedure Call API.
Then it matured to
become RESTful.
2 years 9 months 23 days
Age
187
Paths
192
Commits
103. References
• Souhaila Serbout, Cesare Pautasso, Uwe Zdun, Olaf Zimmermann, From OpenAPI Fragments
to API Pattern Primitives and Smells, Proc. of the European Conference on Pattern
Languages of Programs (EuroPLoP 2021), Kloster Irsee, Germany, July 2021
• Fabio Di Lauro, Souhaila Serbout, Cesare Pautasso,
, Proc. 21st International Conference on Web Engineering
(ICWE2021), Biarritz, France, Springer, May 2021 (Best Paper Award)
• Cesare Pautasso, Ana Ivanchikj, Silvia Schreier,
, Proc. of the 21st European Conference on Pattern Languages of Programs
(EuroPLoP 2016), Kloster Irsee, Germany, July 2016, pp. 4:1-4:22
• Daniel Lübke, Olaf Zimmermann, Cesare Pautasso, Uwe Zdun, Mirko Stocker,
,
Proc. of the 24th European Conference on Pattern Languages of Programs (EuroPLoP 2019),
Irsee, Germany, July 2019
• Olaf Zimmermann, Mirko Stocker, Uwe Zdun, Daniel Lübke, Cesare Pautasso,
, Joint Post-proceedings of the First and Second
International Conference on Microservices (Microservices 2017/2019)
• Cesare Pautasso, , Leanpub, 2020
• Cesare Pautasso, , Leanpub, 2021
Towards Large-scale Empirical
Assessment of Web APIs Evolution
A Pattern Language for RESTful
Conversations
Interface
Evolution Patterns - Balancing Compatibility and Flexibility across Microservices Lifecycles
Introduction to
Microservice API Patterns (MAP)
Beautiful APIs
Beautiful API Evolution