Upgrade to Pro — share decks privately, control downloads, hide ads and more …

API Flow

Cb2527e0c321fc1eb6753c06f45da93c?s=47 Z
May 11, 2016

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

Cb2527e0c321fc1eb6753c06f45da93c?s=128

Z

May 11, 2016
Tweet

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
  66. None
  67. apiary.io/how-to-build-api

  68. apiary.io z@apiary.io @zdne

  69. None
  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