A five-sided prism polarizing Web API development

How do you tackle your API development? Are you diving head-first in the code to get something quickly out the door? Do you start by defining the API contract, that you'll share between your teams and the consumers? Perhaps you prefer to describe your acceptance tests, explaining the behavior you expect from your API. But if you're a storyteller, you'll probably write some use cases, scenarios, to have a better feel for what your API is all about, and how your users will take advantage of it. Or simply, you already have data lying around that wants to set free, and be exposed restfully to the world.

In this session, Guillaume Laforge, Restlet's Product Ninja & Advocate, will highlight different approaches to Web API development, along with their pros & cons. Whether you're starting with code, a contract, tests, documentation, or data, you'll get a glimpse of light into the tasty book of API development recipes.

Transcript

1. A five-sided prism polarizing Web API development Guillaume Laforge Product Ninja & Advocate @glaforge
2. We know about APIs! http://restlet.com
3. We know about APIs! http://restlet.com
5. Pink Floyd Dark side of the moon
6. API PRISM
7. CODE API PRISM
8. DATA CODE API PRISM
9. CONTRACT DATA CODE API PRISM
11. API prism
12. API prism CONTRACT DATA CODE
13. DOC TEST API prism CONTRACT DATA CODE
14. BEHAVIOR DRIVEN DOC TEST API prism CONTRACT DATA CODE
15. Code-first
17. Fire up IDE Setup favorite tech stack Start coding!
18. Fire up IDE Setup favorite tech stack Start coding! Easy to get started with for a developer
19. @glaforge 7 Java annotation hell…
20. @glaforge 7 Java annotation hell… Often annotation heavy in Java: Annotation driven development
22. No code, only annotations, just the method signature!
23. No code, only annotations, just the method signature! And that’s real life code!
24. @glaforge 9 Brittle API contract
25. @glaforge 9 Brittle API contract Refactoring might easily break the implicit contract
26. @glaforge 10 Spaghetti coding
27. @glaforge 10 Spaghetti coding Mixing URL paths, logging, business logic, security constraints, API related annotations…
28. @glaforge 10 Spaghetti coding Cross-cutting concerns intermixed Mixing URL paths, logging, business logic, security constraints, API related annotations…
30. Logging, security, transactions, session management, exception handling…
31. Logging, security, transactions, session management, exception handling… One line of business logic!
32. @glaforge 12 You don’t always have the choice Inheriting existing code bases, services, Web APIs? • not a choice, you’ll work code-first! Mitigation: safe-guards • derive a contract • build step to check
 contract conformance
33. @glaforge 12 You don’t always have the choice Inheriting existing code bases, services, Web APIs? • not a choice, you’ll work code-first! Mitigation: safe-guards • derive a contract • build step to check
 contract conformance An API contract diff tool would be handy, any taker?
34. @glaforge 13 Textual diff vs semantic diff?
35. @glaforge 13 Textual diff vs semantic diff? – Renamed path /users/{user_id} into /v1/users/{user_id} + Added path /v1/users
36. @glaforge 13 Textual diff vs semantic diff? – Renamed path /users/{user_id} into /v1/users/{user_id} + Added path /v1/users Also messages warning the changes are backward incompatible?
37. @glaforge 14 Pros and cons
38. @glaforge 14 Pros and cons Easy to get started with for a developer
39. @glaforge 14 Pros and cons Easy to get started with for a developer Refactoring might easily break the implicit contract
40. @glaforge 14 Pros and cons Easy to get started with for a developer Refactoring might easily break the implicit contract Often annotation heavy in Java: Annotation driven development
41. @glaforge 14 Pros and cons Easy to get started with for a developer Refactoring might easily break the implicit contract Cross-cutting concerns intermixed Often annotation heavy in Java: Annotation driven development
42. DATA-first
44. Existing database: relational, NoSQL, graph Data schema: SQL schema, IDL, JSON schema… Spreadsheet: CSV, Excel, Google Sheets Existing CRUD: CRUD Web API, 
 3rd party Web API
45. Existing database: relational, NoSQL, graph Data schema: SQL schema, IDL, JSON schema… Spreadsheet: CSV, Excel, Google Sheets Existing CRUD: CRUD Web API, 
 3rd party Web API Handy to expose existing data
46. @glaforge Demo: APISpark & 
 Google Sheets wrapper
47. @glaforge 18 Pretty tabular…
48. @glaforge 18 Pretty tabular… Not much control on the API contract
49. @glaforge 19 Dumb API
50. @glaforge 19 Dumb API Dumb API: no business logic out of the box
51. @glaforge 20 Pros and cons
52. @glaforge 20 Pros and cons Handy to expose existing data
53. @glaforge 20 Pros and cons Handy to expose existing data Not much control on the API contract
54. @glaforge 20 Pros and cons Handy to expose existing data Not much control on the API contract Dumb API: no business logic out of the box
55. Contract-first
58. @glaforge 23 Twitter poll
59. @glaforge 23 Twitter poll Not statistically significant :-)
60. @glaforge 23 Twitter poll
61. @glaforge 23 Twitter poll Interesting feedback!
62. @glaforge 23 Twitter poll
64. Contract as the source of truth
65. Contract as the source of truth Also a key communication element!
67. Can derive & generate useful artifacts Client SDKs Server skeletons Static, dynamic, live mocks Test stubs Sandbox & live playgrounds Static documentation Documentation portal
69. Facilitate team collaboration
70. ! "
71. ! " Backend team Frontend team
72. ! " Backend team Frontend team
73. ! " Backend team Frontend team
74. ! " Backend team Frontend team Collaborate on contract Contract ready, mock generated
75. ! " Backend team Frontend team Collaborate on contract Contract ready, mock generated Yay! Shorter time to market!
77. Code generation can overwrite customization
78. Code generation can overwrite customization Favor composition over inheritance!
79. @glaforge 29 Pros and cons
80. @glaforge 29 Pros and cons Contract as the source of truth
81. @glaforge 29 Pros and cons Contract as the source of truth Facilitate team collaboration
82. @glaforge 29 Pros and cons Contract as the source of truth Facilitate team collaboration Can derive & generate useful artifacts
83. @glaforge 29 Pros and cons Contract as the source of truth Facilitate team collaboration Can derive & generate useful artifacts Code generation can overwrite customization
84. TEST-first
85. @glaforge 31 Test Driven Development RED
86. @glaforge 31 Test Driven Development RED GREEN
87. @glaforge 31 Test Driven Development RED GREEN REFACTOR
88. @glaforge 31 Test Driven Development RED GREEN REFACTOR
89. @glaforge Demo: DHC by Restlet
91. Behavior driven: clarifies how the API is working
93. Can ensure API implementation and behavior are in sync
95. Harder to derive & generate useful artifacts
96. Harder to derive & generate useful artifacts Not impossible, but not available yet
98. Hard to define tests without anything to test
99. Hard to define tests without anything to test Mitigation: Solutions with live mocks can ease authoring tests for defining the behavior
100. @glaforge 37 Pros and cons
101. @glaforge 37 Pros and cons Behavior driven: clarifies how the API is working
102. @glaforge 37 Pros and cons Behavior driven: clarifies how the API is working Harder to derive & generate useful artifacts
103. @glaforge 37 Pros and cons Behavior driven: clarifies how the API is working Harder to derive & generate useful artifacts Hard to define tests without anything to test
104. @glaforge 37 Pros and cons Behavior driven: clarifies how the API is working Harder to derive & generate useful artifacts Hard to define tests without anything to test Can ensure API implementation and behavior are in sync
105. DOC-first
106. @glaforge Demo: Silk
108. Use case driven, great for onboarding
110. Doesn’t necessarily generate a useful contract
111. ORANGE
112. Natural language is ambiguous ORANGE
113. @glaforge 43 Pros and cons
114. @glaforge 43 Pros and cons Use case driven, great for onboarding
115. @glaforge 43 Pros and cons Use case driven, great for onboarding Doesn’t necessarily generate a useful contract
116. @glaforge 43 Pros and cons Use case driven, great for onboarding Doesn’t necessarily generate a useful contract Natural language is ambiguous
117. @glaforge Summary
118. @glaforge 45 Five-sided prism polarizing APIs development API prism CONTRACT DATA CODE DOC TEST
119. @glaforge 45 Five-sided prism polarizing APIs development API prism CONTRACT DATA CODE DOC TEST
120. @glaforge 45 Five-sided prism polarizing APIs development API prism CONTRACT DATA CODE DOC TEST No good or one way of tackling Web API development, 
 just tradeoffs!
121. @glaforge 45 Five-sided prism polarizing APIs development API prism CONTRACT DATA CODE DOC TEST No good or one way of tackling Web API development, 
 just tradeoffs! Pick your side, but do it well!
122. @glaforge 46 Get in the flow! The developer workflow! Thursday, May 26 — 1:50pm — Birch The API ecosystem provides powerful tools, online services and definition formats for designing, testing, running, or managing APIs. All share common purposes: improve our productivity when developing an API, allow us to collaborate more effectively, or share our creations with the world! But developers have already invented efficient tactics to streamline their development, gathered experience with and sharpened their tools of trade. The result is that the services or formats mentioned before can actually also get in their way, and interrupt their development flow, as they have to resort to get out of their routine and processes, to use them. What can API tooling vendors do to reconcile the habits of developers with their tools? In this session, Guillaume Laforge, Restlet's Product Ninja & Advocate, will talk about building, versioning & dependency management of API artifacts, scenario & conformance testing, API documentation, continuous integration, multi-environment continuous deployment, and team collaboration! Let’s get back into the development flow!
123. @glaforge Thanks for your attention
124. @glaforge 48 Image credits • Pink Floyd’s Dark Side of the Moon prism
 https://i.ytimg.com/vi/NJQnzmH6jgc/maxresdefault.jpg • Thumb-up
 https://upload.wikimedia.org/wikipedia/commons/thumb/f/fb/Thumbs_up.svg/2000px-Thumbs_up.svg.png • Thumb-down
 https://upload.wikimedia.org/wikipedia/commons/thumb/b/b8/Thumbs_down.svg/1000px- Thumbs_down.svg.png • Engine start
 https://www.flickr.com/photos/npobre/2601582256 • Data graph
 https://upload.wikimedia.org/wikipedia/commons/9/9b/Social_Network_Analysis_Visualization.png • Spaghetti
 https://upload.wikimedia.org/wikipedia/commons/4/4a/Pollo_funghi_spaghetti_-_Paesano_Restaurant.jpg • Northern mocking birg
 https://upload.wikimedia.org/wikipedia/commons/c/cf/Northern_Mocking_bird_- _Mimus_polyglottos.JPG
125. @glaforge 49 Image credits • Boarding
 https://c2.staticflickr.com/4/3024/2503923533_8381d55537_b.jpg • Contract
 https://pixabay.com/static/uploads/photo/2014/08/26/19/20/document-428333_960_720.jpg • Orange paint
 http://www.publicdomainpictures.net/pictures/20000/velka/painting-wall-11291581001pYx.jpg • Orange fruit
 https://www.flickr.com/photos/manicomi/2260527943 • Handbook
 http://www.intexte.net/docenligne/carnet_autie.jpg • Behavior
 http://www.thebluediamondgallery.com/pictures/behavior.jpg • Orsay Museum clock
 https://www.flickr.com/photos/davidden/2320748091 • Factory workers
 https://upload.wikimedia.org/wikipedia/commons/0/08/Seagate_Wuxi_China_Factory_Tour.jpg
126. @glaforge 50 Image credits • Hell
 https://upload.wikimedia.org/wikipedia/commons/f/f5/ An_angel_leading_a_soul_into_hell._Oil_painting_by_a_followe_Wellcome_L0030887.jpg • Excel
 https://i.ytimg.com/vi/nbYi2x84EW0/maxresdefault.jpg • Broken glass
 https://upload.wikimedia.org/wikipedia/commons/thumb/6/67/Broken_glass.jpg/1280px-Broken_glass.jpg • Truth
 https://pixabay.com/static/uploads/photo/2013/07/25/11/52/truth-166853_960_720.jpg • Car assembly line
 https://upload.wikimedia.org/wikipedia/commons/f/f1/Hyundai_car_assembly_line.jpg • Team collaboration
 https://static.pexels.com/photos/7092/desk-office-hero-workspace.jpg