API Flow

My talk at GitHub Satellite Amsterdam (5/11/2016) on how to build APIs. #githubsatellite #statelliteAMS

Recording: https://www.youtube.com/watch?v=cwz3U82mC-Y

Transcript

1. API FLOW Z (@zdne) Apiary
2. APIs, HOW DID WE GET HERE?
3. INTERGALACTIC COMPUTER NETWORK
4. INTERGALACTIC COMPUTER NETWORK How would completely unrelated beings communicate?
5. THEY WOULD HAVE TO FIGURE OUT
6. INTERGALACTIC COMPUTER NETWORK How would distributed components communicate?
7. THEY WOULD HAVE TO FIGURE OUT
8. OR?
9. HAVE SOME A PRIORI UNDERSTANDING
10. SHARED UNDERSTANDING AHEAD OF TIME 1 A component exposes an interface
11. SHARED UNDERSTANDING AHEAD OF TIME 1 A component exposes an interface 2 Some humans write a lot of text to document it
12. SHARED UNDERSTANDING AHEAD OF TIME 1 A component exposes an interface 2 Some humans write a lot of text to document it 3 Some other humans read it
13. SHARED UNDERSTANDING AHEAD OF TIME 1 A component exposes an interface 2 Some humans write a lot of text to document it 3 Some other humans read it 4 And program another component to use the interface
14. SHARED UNDERSTANDING AHEAD OF TIME 1 EX PO SE IN TERFAC E W RITE D O C S REA D D O C S PRO G RA M C LIEN T 2 3 4
15. SHARED UNDERSTANDING AHEAD OF TIME 1 EX PO SE IN TERFAC E W RITE D O C S REA D D O C S PRO G RA M C LIEN T 2 3 4
16. CLASSIC API FLOW 1 D EVELO PM EN T D ELIVERY C O N SU M PTIO N A N A LYSIS 2 3 4
17. PROBLEMS OF SHARED UNDERSTANDING AHEAD OF TIME • Error-prone • Brittle system • Tight-coupling, prohibits changes • Requires couple of iterations to get it right • Does not scale
18. PROBLEMS OF SHARED UNDERSTANDING AHEAD OF TIME • Error-prone • Brittle system • Tight-coupling, prohibits changes • Requires couple of iterations to get it right • Does not scale humans do errors versioning anyone? heard about broken clients? did clients use your API as expected? hire more programmers to write more docs
19. WE CAN PREVENT OR MITIGATE MOST OF THESE
20. API FLOW
21. DESIGN-FIRST
22. 4 STAGES OF API MATURITY API as a by- product of building apps API documentation generated from code Design-first API Development API Design Consistency
23. API IS A PRODUCT SO TREAT IT AS A PRODUCT
24. DESIGN-FIRST FLOW 2 D EVELO PM EN T D ELIVERY C O N SU M PTIO N A N A LYSIS 3 4 5 1 D ESIG N
25. PREPARE YOUR ORGANIZATION 1 PREPA RATIO N D ESIG N D EVELO PM EN T D ELIVERY C O N SU M PTIO N A N A LYSIS 2 3 4 5 6
26. PREPARE YOUR ORGANIZATION 1 PREPA RATIO N D ESIG N D EVELO PM EN T D ELIVERY C O N SU M PTIO N A N A LYSIS 2 3 4 5 6 reuse for improved DX through consistency
27. STILL A WATERFALL
28. PROTOTYPE
29. DESIGN & PROTOTYPE 1 PREPA RATIO N D ESIG N & PRO TO TYPE D EVELO PM EN T D ELIVERY C O N SU M PTIO N A N A LYSIS 2 3 4 5 6
30. 1 PREPA RATIO N DESIGN & PROTOTYPE D ESIG N & PRO TO TYPE D EVELO PM EN T D ELIVERY C O N SU M PTIO N A N A LYSIS 2 3 4 5 6
31. ANALYZE & ITERATE
32. 1 PREPA RATIO N ANALYZE & ITERATE D ESIG N & PRO TO TYPE D EVELO PM EN T D ELIVERY C O N SU M PTIO N A N A LYSIS 2 3 4 5 6
33. API FLOW PHASES STEPS
34. 1 PREPA RATIO N API FLOW PHASES STEPS D ESIG N & PRO TO TYPE D EVELO PM EN T D ELIVERY C O N SU M PTIO N A N A LYSIS 2 3 4 5 6
35. PREPARATION 1 1 Define Domain Semantics
36. PREPARATION 1 1 Define Domain Semantics 2 Choose Architectural Style
37. PREPARATION 1 1 Define Domain Semantics 2 Choose Architectural Style 3 Formalize Style Guide
38. DESIGN & PROTOTYPE 2 1 Identify Resources
39. DESIGN & PROTOTYPE 2 1 Identify Resources 2 Define Resource States
40. DESIGN & PROTOTYPE 2 1 Identify Resources 2 Define Resource States 3 Write API Description • API Blueprint • OpenAPI Spec (Swagger) • Word / Google Doc • Email • WADL, WSDL, RAML GitHub Flow
41. DESIGN & PROTOTYPE 2 1 Identify Resources 2 Define Resource States 3 Write API Description 4 Use Mock Server 5 C O N SU M PTIO N GitHub Flow
42. DESIGN & PROTOTYPE 2 1 Identify Resources 2 Define Resource States 3 Write API Description 4 Use Mock Server 5 Share & Review 5 C O N SU M PTIO N GitHub Flow GitHub Flow
43. SHARE & REVIEW
44. THE REAL DIFFERENCE
45. THE DIFFERENCE WITH GITHUB FLOW
46. GITHUB FLOW CREATE A BRANCH Create a branch in your project where you can safely experiment and make changes. OPEN A PULL REQUEST Use a pull request to get feedback on your changes from people down the hall or ten time zones away. MERGE AND DEPLOY Merge your changes into your master branch and deploy your code. ADD COMMITS DISCUSS AND REVIEW GitHub provides tools for easier collaboration and code sharing from any device. Start collaborating with millions of developers today! GitHub is the best way to build software together. WORK FAST WORK SMART THE GITHUB FLOW The GitHub Flow is a lightweight, branch-based workflow that's great for teams and projects with regular deployments. Find this and other guides at http://guides.github.com/. Source: GitHub https://guides.github.com/introduction/flow/ GitHub Flow
47. ( ) backend developer stake holder client architect writer INVOLVE EVERYBODY
48. THE REAL DIFFERENCE 1 D EVELO PM EN T D ELIVERY C O N SU M PTIO N A N A LYSIS 2 3 4 1 PREPA RATIO N D ESIG N & PRO TO TYPE D EVELO PM EN T D ELIVERY C O N SU M PTIO N A N A LYSIS 2 3 4 5 6
49. THE REAL DIFFERENCE 1 D EVELO PM EN T D ELIVERY C O N SU M PTIO N A N A LYSIS 2 3 4 1 PREPA RATIO N D ESIG N & PRO TO TYPE D EVELO PM EN T D ELIVERY C O N SU M PTIO N A N A LYSIS 2 3 4 5 6 )( )(
50. DEVELOPMENT 3 1 Description + Implementation GitHub Flow • Contract
51. DEVELOPMENT 3 1 2 Develop Server GitHub Flow Description + Implementation GitHub Flow
52. DEVELOPMENT 3 1 Description + Implementation 2 Develop Server 3 Test Locally GitHub Flow GitHub Flow Dredd github.com/apiaryio/dredd
53. DEVELOPMENT 3 1 2 Develop Server 3 Test Locally 4 Test in CI GitHub Flow Description + Implementation GitHub Flow
54. Tests in CI Mock Server Documentation Call Inspector API Description CONTRACT INTEGRATION
55. DEVELOPMENT 3 1 2 Develop Server 3 Test Locally 4 Test in CI 5 Deploy GitHub Flow Description + Implementation GitHub Flow Develop Track: Using pull requests to drive continuous delivery Guðmundur Bjarni Ólafsson (Heroku) Heroku Flow
56. DELIVERY 4 1 Share API Description
57. DELIVERY 4 1 Share API Description 2 Share Documentation
58. DELIVERY 4 1 Share API Description 2 Share Documentation 3 API Management
59. CONSUMPTION 5 1 Read Documentation
60. CONSUMPTION 5 1 Read Documentation 2 Experiment with API
61. CONSUMPTION 5 1 Read Documentation 2 Experiment with API 3 Develop client against Mock Server GitHub Flow
62. CONSUMPTION 5 1 Read Documentation 2 Experiment with API 3 Develop client against Mock Server 4 Develop client against Production via Debugging Proxy GitHub Flow GitHub Flow
63. ANALYSIS 6 1 Collect the Feedback
64. ANALYSIS 6 1 Collect the Feedback 2 Iterate
65. 1 PREPA RATIO N API FLOW D ESIG N & PRO TO TYPE D EVELO PM EN T D ELIVERY C O N SU M PTIO N A N A LYSIS 2 3 4 5 6
67. apiary.io/how-to-build-api
68. apiary.io z@apiary.io @zdne
70. API LIFECYCLE
71. CLASSIC API LIFECYCLE Development Delivery Consumption Analysis
72. Preparation Design Development Delivery Consumption Analysis DESIGN-FIRST API LIFECYCLE
73. Preparation Design & Prototype Development Delivery Consumption Analysis AGILE LIFECYCLE
74. API FLOW PHASES
75. 1 PREPA RATIO N API FLOW PHASES
76. 1 PREPA RATIO N API FLOW PHASES D ESIG N & PRO TO TYPE 2
77. 1 PREPA RATIO N API FLOW PHASES D ESIG N & PRO TO TYPE D EVELO PM EN T 2 3
78. 1 PREPA RATIO N API FLOW PHASES D ESIG N & PRO TO TYPE D EVELO PM EN T D ELIVERY 2 3 4
79. 1 PREPA RATIO N API FLOW PHASES D ESIG N & PRO TO TYPE D EVELO PM EN T D ELIVERY C O N SU M PTIO N 2 3 4 5
80. 1 PREPA RATIO N API FLOW PHASES D ESIG N & PRO TO TYPE D EVELO PM EN T D ELIVERY C O N SU M PTIO N A N A LYSIS 2 3 4 5 6
81. 1 PREPA RATIO N API FLOW PHASES D ESIG N & PRO TO TYPE D EVELO PM EN T D ELIVERY C O N SU M PTIO N A N A LYSIS 2 3 4 5 6
82. 1 PREPA RATIO N API FLOW PHASES D ESIG N & PRO TO TYPE D EVELO PM EN T D ELIVERY C O N SU M PTIO N A N A LYSIS 2 3 4 5 6
83. REFERENCES
84. REFERENCES • How to Build APIs: https://apiary.io/how-to-build-api • Apiary: https://apiary.io/ • J.C.R. Licklider: https://en.wikipedia.org/wiki/J._C._R._Licklider • Future of Programming: https://vimeo.com/71278954 • Communicating with Aliens: http://amundsen.com/blog/archives/1146 • GitHub Flow: https://guides.github.com/introduction/flow/ • Heroku Flow: https://www.heroku.com/continuous-delivery • Dredd: https://github.com/apiaryio/dredd