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

Get in the flow! The API developer workflow!

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!

Guillaume Laforge

May 26, 2016
Tweet

More Decks by Guillaume Laforge

Other Decks in Technology

Transcript

  1. Get in the flow!
    The API developer
    workflow!
    Guillaume Laforge
    Product Ninja & Advocate
    @glaforge

    View Slide

  2. Get in the flow!
    The API developer
    workflow!
    Guillaume Laforge
    Product Ninja & Advocate
    @glaforge
    Slides will be available here:
    speakerdeck.com/glaforge

    View Slide

  3. We know
    about
    APIs!
    http://restlet.com

    View Slide

  4. We know
    about
    APIs!
    http://restlet.com

    View Slide

  5. @glaforge
    3
    Goals of this talk
    !"

    View Slide

  6. @glaforge
    3
    Goals of this talk
    Better understanding
    developers by getting into
    their shoes
    !"

    View Slide

  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!
    !"

    View Slide

  8. @glaforge
    4
    What do we want?

    View Slide

  9. @glaforge
    4
    Productivity

    Making developers
    more productive
    What do we want?

    View Slide

  10. @glaforge
    4
    Productivity

    Making developers
    more productive
    Delight

    Delighting
    developers with a
    great experience
    What do we want?

    View Slide

  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?

    View Slide

  12. @glaforge
    From lifecycle to the flow

    View Slide

  13. View Slide

  14. Plan / Design
    Build / Integrate
    Operate / Manage
    Share / Engage

    View Slide

  15. View Slide

  16. Develop
    Publish
    Manage
    Monitor

    View Slide

  17. View Slide

  18. Analysis
    Development
    Operations
    Retire

    View Slide

  19. View Slide

  20. What are the
    developer activities
    associated with
    those stages?

    View Slide

  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

    View Slide

  22. Turning
    round in
    circles

    View Slide

  23. Quite
    immutable

    View Slide

  24. Like w
    aterfall
    development

    View Slide

  25. More
    like a
    Workflow

    View Slide

  26. Let’s get
    in the flow

    View Slide

  27. No interruption

    View Slide

  28. Tools aligned
    with existing
    workflows

    View Slide

  29. Tools aligned
    with existing
    workflows
    Helps avoid
    resistance to
    change

    View Slide

  30. Tools aligned
    with existing
    workflows
    Helps avoid
    resistance to
    change
    You’re more
    productive with
    the tools you
    know

    View Slide

  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

    View Slide

  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

    View Slide

  33. Let’s get back to
    the developer

    View Slide

  34. @glaforge
    Typical developer activities

    View Slide

  35. @glaforge
    20
    Typical developer activities

    View Slide

  36. @glaforge
    20
    Typical developer activities
    develop
    automate
    build dependencies
    test
    continuous
    document
    deploy
    guidelines
    versioning
    collaborate
    communicate
    design

    View Slide

  37. Develop
    in an IDE

    View Slide

  38. @glaforge
    22
    Not my IDE!
    A standalone API designer makes the developer leave his IDE

    View Slide

  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

    View Slide

  40. Automate and
    build the project

    View Slide

  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

    View Slide

  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…

    View Slide

  43. View Slide

  44. View Slide

  45. View Slide

  46. View Slide

  47. @glaforge
    26
    Go meta!
    • Built an API SaaS tool?
    • Eat your own dog food
    • Show you know about APIs!

    View Slide

  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

    View Slide

  49. View Slide

  50. APISpark provides
    a meta-API
    to go beyond the UI

    View Slide

  51. APISpark provides
    a meta-API
    to go beyond the UI
    Not cleaned up 

    or officially 

    published yet!

    View Slide

  52. APISpark provides
    a meta-API
    to go beyond the UI
    Not cleaned up 

    or officially 

    published yet!

    View Slide

  53. Version
    Code
    & API

    View Slide

  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
    ! " $

    View Slide

  55. @glaforge
    30
    Version your code base

    View Slide

  56. @glaforge
    31
    Version your code base

    View Slide

  57. @glaforge
    31
    Version your code base
    Tools should integrate with
    your version control, to store
    and update API definitions,
    test scenarios, etc.

    View Slide

  58. DEpends on
    versioned
    libraries

    View Slide

  59. @glaforge
    33
    The pain of switching tools…
    %

    View Slide

  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

    View Slide

  61. @glaforge
    34
    Contract-first and code generation

    View Slide

  62. @glaforge
    34
    Contract-first and code generation
    Mocks
    static
    dynam
    ic
    live

    View Slide

  63. @glaforge
    34
    Contract-first and code generation
    Mocks
    Client SDKs
    static
    dynam
    ic
    live

    View Slide

  64. @glaforge
    34
    Contract-first and code generation
    Mocks
    Server skeletons
    Client SDKs
    static
    dynam
    ic
    live

    View Slide

  65. @glaforge
    35
    Problems with code generation…
    %

    View Slide

  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?

    View Slide

  67. @glaforge
    36
    Code generation & dependencies

    View Slide

  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

    View Slide

  69. View Slide

  70. All popular tech
    stack repositories
    supported

    View Slide

  71. RUN
    TESTS

    View Slide

  72. View Slide

  73. View Slide

  74. Follow company
    Guidelines

    View Slide

  75. View Slide

  76. @glaforge
    42
    Company guidelines

    View Slide

  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

    View Slide

  78. Continuousl
    y
    build, test
    & deploy

    View Slide

  79. @glaforge
    44
    Integrate with existing solutions

    View Slide

  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

    View Slide

  81. View Slide

  82. View Slide

  83. Document
    your API

    View Slide

  84. Document
    your API
    You’ve got a
    story to tell!

    View Slide

  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

    View Slide

  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

    View Slide

  87. bit.ly/howfarapi

    View Slide

  88. View Slide

  89. View Slide

  90. Collaborate
    as a team

    View Slide

  91. @glaforge
    51
    Simplify collaboration: who did what?
    %

    View Slide

  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!

    View Slide

  93. @glaforge
    52
    Simplify collaboration

    View Slide

  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

    View Slide

  95. @glaforge
    53
    Simplify collaboration

    View Slide

  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

    View Slide

  97. Communicate

    View Slide

  98. @glaforge
    55
    Facilitate communication

    View Slide

  99. @glaforge
    55
    Facilitate communication
    • Notifications

    send notifications of changes

    through Slack, HipChat, and friends
    • Email is still a thing :-)

    View Slide

  100. Deploy and
    ship the
    API

    View Slide

  101. @glaforge
    57
    Deploy, ship, monitor, analyze…
    • Highly depends on your
    deployment platform
    • API portal for documentation,
    discovery & onboarding
    • Monitor continuously

    View Slide

  102. @glaforge
    Summary

    View Slide

  103. @glaforge
    59
    Summary
    ! " $

    View Slide

  104. @glaforge
    59
    Summary
    Don’t get in the
    way of the API
    developer!
    ! " $

    View Slide

  105. @glaforge
    59
    Summary
    Don’t get in the
    way of the API
    developer!
    Integrate with the
    usual tools of the
    developer
    ! " $

    View Slide

  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
    ! " $

    View Slide

  107. @glaforge
    Thanks for your attention

    View Slide

  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

    View Slide

  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

    View Slide

  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

    View Slide

  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

    View Slide