Get in the flow! The API developer workflow!

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!

Transcript

1. Get in the flow! The API developer workflow! Guillaume Laforge Product Ninja & Advocate @glaforge
2. Get in the flow! The API developer workflow! Guillaume Laforge Product Ninja & Advocate @glaforge Slides will be available here: speakerdeck.com/glaforge
3. We know about APIs! http://restlet.com
4. We know about APIs! http://restlet.com
5. @glaforge 3 Goals of this talk !"
6. @glaforge 3 Goals of this talk Better understanding developers by getting into their shoes !"
7. @glaforge 3 Goals of this talk Better understanding developers by getting into their shoes How API tooling can help developers rather than get in their way! !"
8. @glaforge 4 What do we want?
9. @glaforge 4 Productivity 
 Making developers more productive What do we want?
10. @glaforge 4 Productivity 
 Making developers more productive Delight 
 Delighting developers with a great experience What do we want?
11. @glaforge Empowerment 
 Empowering developers to realize her/his API 4 Productivity 
 Making developers more productive Delight 
 Delighting developers with a great experience What do we want?
12. @glaforge From lifecycle to the flow
14. Plan / Design Build / Integrate Operate / Manage Share / Engage
16. Develop Publish Manage Monitor
18. Analysis Development Operations Retire
20. What are the developer activities associated with those stages?
21. @glaforge 10 The API flow • Blog post on the API flow
 http://restlet.com/blog/2016/02/18/the-api-flow/ • Presentations from Zdenek & Emmanuel on the API flow
 https://speakerdeck.com/zdne/api-flow
 https://speakerdeck.com/paraskakis/scaling-the-api-flow • More details on the API flow
 https://apiary.io/how-to-build-api
22. Turning round in circles
23. Quite immutable
24. Like w aterfall development
25. More like a Workflow
26. Let’s get in the flow
27. No interruption
28. Tools aligned with existing workflows
29. Tools aligned with existing workflows Helps avoid resistance to change
30. Tools aligned with existing workflows Helps avoid resistance to change You’re more productive with the tools you know
31. Tools aligned with existing workflows Helps avoid resistance to change You’re more productive with the tools you know Easier for adoption of your solutions
32. Tools aligned with existing workflows Helps avoid resistance to change You’re more productive with the tools you know Easier for adoption of your solutions Less interruption
33. Let’s get back to the developer
34. @glaforge Typical developer activities
35. @glaforge 20 Typical developer activities
36. @glaforge 20 Typical developer activities develop automate build dependencies test continuous document deploy guidelines versioning collaborate communicate design
37. Develop in an IDE
38. @glaforge 22 Not my IDE! A standalone API designer makes the developer leave his IDE
39. @glaforge 22 Not my IDE! A standalone API designer makes the developer leave his IDE Integrate your API tooling into existing IDEs or editors to avoid leaving a familiar environment
40. Automate and build the project
41. @glaforge 24 Integrate with developer tools • Developers are used to a certain tech stack • and they like the command-line too • They don’t want to use tools from other stacks
42. @glaforge 24 Integrate with developer tools • Developers are used to a certain tech stack • and they like the command-line too • They don’t want to use tools from other stacks Ex: API testing tool Provide test runners for different tech stacks, like 
 Java, NPM, Gems…
47. @glaforge 26 Go meta! • Built an API SaaS tool? • Eat your own dog food • Show you know about APIs!
48. @glaforge 26 Go meta! • Built an API SaaS tool? • Eat your own dog food • Show you know about APIs! An API solution should have its own REST API, to go beyond what the UI offers
50. APISpark provides a meta-API to go beyond the UI
51. APISpark provides a meta-API to go beyond the UI Not cleaned up 
 or officially 
 published yet! ❗
52. APISpark provides a meta-API to go beyond the UI Not cleaned up 
 or officially 
 published yet! ❗
53. Version Code & API
54. @glaforge 29 3 key elements to version Code base implementing 
 the API
 API version 
 as your API 
 evolves
 Artifacts 
 (client SDKs, server skeletons, mocks) along the API ! " $
55. @glaforge 30 Version your code base
56. @glaforge 31 Version your code base
57. @glaforge 31 Version your code base Tools should integrate with your version control, to store and update API definitions, test scenarios, etc.
58. DEpends on versioned libraries
59. @glaforge 33 The pain of switching tools… %
60. @glaforge 33 The pain of switching tools… % I’d like to be able to commit from the tool itself if I want I don’t want to import / export all the time between different tools Tools should let me work locally on my machine, and not just in the cloud
61. @glaforge 34 Contract-first and code generation
62. @glaforge 34 Contract-first and code generation Mocks static dynam ic live
63. @glaforge 34 Contract-first and code generation Mocks Client SDKs static dynam ic live
64. @glaforge 34 Contract-first and code generation Mocks Server skeletons Client SDKs static dynam ic live
65. @glaforge 35 Problems with code generation… %
66. @glaforge 35 Problems with code generation… % I have to commit the client SDK in version control manually But I tweaked the code of my skeleton. API changes will change the mock and overwrite my changes! The artifacts can’t be downloaded from my repo manager How can I easily use the mock in my tests and my build?
67. @glaforge 36 Code generation & dependencies
68. @glaforge 36 Code generation & dependencies • Version your artifacts according to the revisions and API versions • Use artifact management solutions 
 or fake them in your product • Make it your mantra: 
 composition over inheritance
70. All popular tech stack repositories supported
71. RUN TESTS
74. Follow company Guidelines
76. @glaforge 42 Company guidelines
77. @glaforge 42 Company guidelines • Contract-first? Tools should check that an API implementation 
 conforms with its contract
 • Allow developers to define custom conformance rules, to comply with guidelines defined by the company
78. Continuousl y build, test & deploy
79. @glaforge 44 Integrate with existing solutions
80. @glaforge 44 Integrate with existing solutions • Integrate with existing build and continuous integration solutions, as well as command-line tools • Support notion of environments • Provide sandboxes, containers, 
 or virtualized APIs
83. Document your API
84. Document your API You’ve got a story to tell!
85. @glaforge 47 Documentation isn’t a list of paths • API consumers need more than just a list of paths and methods, but need to understand how to use your API for their use case
86. @glaforge 47 Documentation isn’t a list of paths • API consumers need more than just a list of paths and methods, but need to understand how to use your API for their use case • Use case oriented documentation • Facilitate onboarding
87. bit.ly/howfarapi
90. Collaborate as a team
91. @glaforge 51 Simplify collaboration: who did what? %
92. @glaforge 51 Simplify collaboration: who did what? % My colleague added a new resource I didn’t notice! My QA friend updated my test scenario, hence why it’s failing now! I don’t have access to the API configuration under my role I can’t wait for the other team to finish the API I need! I want a stub!
93. @glaforge 52 Simplify collaboration
94. @glaforge 52 Simplify collaboration • Show activity streams 
 to show who did what and when
 (notifications or logs at minimum)
 • Provide different levels of roles
 or anybody can do anything 
 but are tracked
95. @glaforge 53 Simplify collaboration
96. @glaforge 53 Simplify collaboration • Provide a « diff » facility to see what has changed between two iterations
 • Report if the changes made introduce breaking changes in the contract of your API
97. Communicate
98. @glaforge 55 Facilitate communication
99. @glaforge 55 Facilitate communication • Notifications
 send notifications of changes
 through Slack, HipChat, and friends • Email is still a thing :-)
100. Deploy and ship the API
101. @glaforge 57 Deploy, ship, monitor, analyze… • Highly depends on your deployment platform • API portal for documentation, discovery & onboarding • Monitor continuously
102. @glaforge Summary
103. @glaforge 59 Summary ! " $
104. @glaforge 59 Summary Don’t get in the way of the API developer! ! " $
105. @glaforge 59 Summary Don’t get in the way of the API developer! Integrate with the usual tools of the developer ! " $
106. @glaforge 59 Summary Don’t get in the way of the API developer! Integrate with the usual tools of the developer From a lifecycle of tasks, towards a flow of developer activities ! " $
107. @glaforge Thanks for your attention
108. @glaforge 61 Image credits • Lifecycle of a frog
 http://www.supercoloring.com/sites/default/files/styles/coloring_full/public/cif/2015/04/life-cycle-of-a-frog- coloring-pages.png • Statue
 https://static.pexels.com/photos/4483/black-and-white-historical-statue-monument.jpg • Developer hands on keyboard
 https://www.jisc.ac.uk/sites/default/files/independent-developer.jpg • Waterfall
 https://upload.wikimedia.org/wikipedia/commons/0/08/Canada_waterfall_2.jpg • GTD workflow
 https://s-media-cache-ak0.pinimg.com/736x/d8/19/0b/d8190b4ce0987c1138d35dda8d8054e2.jpg • Zen stones and flow
 https://i.ytimg.com/vi/S3EppVo67hI/maxresdefault.jpg • Pause button
 https://upload.wikimedia.org/wikipedia/commons/thumb/7/71/Media-playback-pause.svg/2000px-Media- playback-pause.svg.png
109. @glaforge 62 Image credits • Coding
 https://www.flickr.com/photos/yusamoilov/13334080323 • Welding
 http://www.public-domain-image.com/free-images/people/male-men/metal-factory-employees.jpg • Chains
 https://static.pexels.com/photos/4000/yellow-chain.jpg • Tests
 https://upload.wikimedia.org/wikipedia/commons/f/fa/Cito_Eindtoets_Basisonderwijs.JPG • Cogs / clockwork
 https://upload.wikimedia.org/wikipedia/commons/thumb/2/2f/Clock_Cogs.jpg/1280px-Clock_Cogs.jpg • Book / paper
 https://upload.wikimedia.org/wikipedia/commons/e/e5/Stack_of_Copy_Paper.jpg • Cargo ship
 https://www.flickr.com/photos/alanrmiles/3312687965
110. @glaforge 63 Image credits • Commandments
 https://c2.staticflickr.com/6/5245/5304492399_805a329467_b.jpg • V1 flying bomb • Collaborate
 https://static.pexels.com/photos/7092/desk-office-hero-workspace.jpg • Spiraling stairs
 https://janew13.files.wordpress.com/2009/09/spiral.jpg • Light bulb
 https://upload.wikimedia.org/wikipedia/commons/thumb/3/3c/Crystal_Clear_app_ktip.svg/1024px- Crystal_Clear_app_ktip.svg.png • Bike lane + phone
 https://upload.wikimedia.org/wikipedia/commons/1/1e/Telephone_booth_in_the_way_of_bicycle_tracks.jpg • Shoes
 https://static.pexels.com/photos/5886/feet-legs-shoes-foot.jpg • DevOps
 https://upload.wikimedia.org/wikipedia/commons/thumb/b/b5/Devops.svg/2000px-Devops.svg.png
111. @glaforge 64 Image credits • Coding
 https://www.flickr.com/photos/yusamoilov/13334080323 • Welding
 http://www.public-domain-image.com/free-images/people/male-men/metal-factory-employees.jpg • Chains
 https://static.pexels.com/photos/4000/yellow-chain.jpg • Tests
 https://upload.wikimedia.org/wikipedia/commons/f/fa/Cito_Eindtoets_Basisonderwijs.JPG • Cogs / clockwork
 https://upload.wikimedia.org/wikipedia/commons/thumb/2/2f/Clock_Cogs.jpg/1280px- Clock_Cogs.jpg • Book / paper
 https://upload.wikimedia.org/wikipedia/commons/e/e5/Stack_of_Copy_Paper.jpg • Cargo ship
 https://www.flickr.com/photos/alanrmiles/3312687965