Beautiful APIs

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.

More details: https://leanpub.com/b/beautiful-apis/

Transcript

1. Beautiful APIs Cesare Pautasso c.pautasso@ieee.org Opening Keynote Fifteenth IEEE International Conference on Service-Oriented System Engineering (SOSE2021) August 23, 2021, Virtual Oxford, UK http://www.pautasso.info/
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
7. Every Component has an Interface Consumer Provider
8. Every Architecture has an API
9. Connect and Separate Outside Inside API
10. Application Developers (1998)
11. Integration Developers (2013)
12. Mashup Developers (2014)
13. Low Code ''Developers'' (2020)
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
17. Operations = Resource Path + Method
18. Multiple Representations
19. Read-Only Collection
20. Read-Only
21. Read-Only
22. Read-Only
23. Read-Write
24. Read-Write
25. Read-Write-Delete
26. Remote Procedure Call
27. Actions
28. Actions and HTTP Methods
29. Structured Read-Write
30. Deep Structured Read-Write
31. Collection
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
33. CRUMD Collection
34. CRUMD Collections
35. Collections Mix
36. Collection with Commands
37. GET, POST, DELETE, PUT
38. GET, POST, DELETE, PUT, PATCH
39. PUT Setters
40. POST-less
41. NoSQL API
42. CRUD API
43. SQL API
46. SpareMoney
47. SpareMoney
48. CarService API
49. CarService API
50. OpenTrials API
51. OpenTrials API
52. Flat API
53. Flat API
54. OpenPAI RESTful API
55. OpenPAI RESTful API
56. Clamp Rest API
57. Clamp Rest API
58. ID Vault
59. ID Vault
60. LibOpenStorage
61. LibOpenStorage
62. BMInventory
63. BMInventory
64. MADApp API
65. MADApp API
67. Welcome to the guided tour of the Beautiful API Evolution virtual exhibition.
68. SpareMoney Welcome to the guided tour of the Beautiful API Evolution virtual exhibition. 1 month 11 days Age 27 Paths 45 Commits
69. Each line represents an operation. Its color corresponds to the HTTP method.
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
77. The circular rings represent time intervals. This read-only API is more than one year old.
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
95. This 2.5-years-old API was born as a Remote Procedure Call API. Then it matured to become RESTful.
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
97. Beautiful API Evolution Beautiful API Evolution
98. Web ↔ APIs Web as a tunnel 2000 ''It's not RESTful enough'' 2010 Web browser as a tunnel 2020
101. More Examples • Cesare Pautasso, , Leanpub, 2020 • Cesare Pautasso, , Leanpub, 2021 Beautiful APIs Beautiful API Evolution
102. Microservice API Design Patterns https://microservice-api-patterns.org
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