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

A five-sided prism polarizing Web API development

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.

Guillaume Laforge

May 25, 2016
Tweet

More Decks by Guillaume Laforge

Other Decks in Technology

Transcript

  1. A five-sided prism
    polarizing Web API
    development
    Guillaume Laforge
    Product Ninja & Advocate
    @glaforge

    View Slide

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

    View Slide

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

    View Slide

  4. View Slide

  5. Pink Floyd
    Dark side of the moon

    View Slide

  6. API
    PRISM

    View Slide

  7. CODE
    API
    PRISM

    View Slide

  8. DATA
    CODE
    API
    PRISM

    View Slide

  9. CONTRACT
    DATA
    CODE
    API
    PRISM

    View Slide

  10. View Slide

  11. API
    prism

    View Slide

  12. API
    prism
    CONTRACT DATA
    CODE

    View Slide

  13. DOC
    TEST
    API
    prism
    CONTRACT DATA
    CODE

    View Slide

  14. BEHAVIOR
    DRIVEN
    DOC
    TEST
    API
    prism
    CONTRACT DATA
    CODE

    View Slide

  15. Code-first

    View Slide

  16. View Slide

  17. Fire up IDE
    Setup favorite
    tech stack
    Start coding!

    View Slide

  18. Fire up IDE
    Setup favorite
    tech stack
    Start coding!
    Easy to get
    started with
    for a developer

    View Slide

  19. @glaforge
    7
    Java annotation hell…

    View Slide

  20. @glaforge
    7
    Java annotation hell…
    Often annotation
    heavy in Java:
    Annotation driven
    development

    View Slide

  21. View Slide

  22. No code, only
    annotations, just the
    method signature!

    View Slide

  23. No code, only
    annotations, just the
    method signature!
    And that’s real life code!

    View Slide

  24. @glaforge
    9
    Brittle API contract

    View Slide

  25. @glaforge
    9
    Brittle API contract
    Refactoring might
    easily break the
    implicit contract

    View Slide

  26. @glaforge
    10
    Spaghetti coding

    View Slide

  27. @glaforge
    10
    Spaghetti coding
    Mixing URL paths, logging,
    business logic, security
    constraints, API related
    annotations…

    View Slide

  28. @glaforge
    10
    Spaghetti coding
    Cross-cutting
    concerns
    intermixed
    Mixing URL paths, logging,
    business logic, security
    constraints, API related
    annotations…

    View Slide

  29. View Slide

  30. Logging, security,
    transactions, session
    management, exception
    handling…

    View Slide

  31. Logging, security,
    transactions, session
    management, exception
    handling…
    One line of
    business logic!

    View Slide

  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

    View Slide

  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?

    View Slide

  34. @glaforge
    13
    Textual diff vs semantic diff?

    View Slide

  35. @glaforge
    13
    Textual diff vs semantic diff?
    – Renamed path /users/{user_id} into /v1/users/{user_id}
    + Added path /v1/users

    View Slide

  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?

    View Slide

  37. @glaforge
    14
    Pros and cons

    View Slide

  38. @glaforge
    14
    Pros and cons
    Easy to get
    started with
    for a developer

    View Slide

  39. @glaforge
    14
    Pros and cons
    Easy to get
    started with
    for a developer
    Refactoring might
    easily break the
    implicit contract

    View Slide

  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

    View Slide

  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

    View Slide

  42. DATA-first

    View Slide

  43. View Slide

  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

    View Slide

  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

    View Slide

  46. @glaforge
    Demo: APISpark & 

    Google Sheets wrapper

    View Slide

  47. @glaforge
    18
    Pretty tabular…

    View Slide

  48. @glaforge
    18
    Pretty tabular…
    Not much
    control on the
    API contract

    View Slide

  49. @glaforge
    19
    Dumb API

    View Slide

  50. @glaforge
    19
    Dumb API
    Dumb API:
    no business
    logic out of
    the box

    View Slide

  51. @glaforge
    20
    Pros and cons

    View Slide

  52. @glaforge
    20
    Pros and cons
    Handy to
    expose
    existing data

    View Slide

  53. @glaforge
    20
    Pros and cons
    Handy to
    expose
    existing data
    Not much
    control on the
    API contract

    View Slide

  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

    View Slide

  55. Contract-first

    View Slide

  56. View Slide

  57. View Slide

  58. @glaforge
    23
    Twitter poll

    View Slide

  59. @glaforge
    23
    Twitter poll
    Not statistically
    significant :-)

    View Slide

  60. @glaforge
    23
    Twitter poll

    View Slide

  61. @glaforge
    23
    Twitter poll
    Interesting
    feedback!

    View Slide

  62. @glaforge
    23
    Twitter poll

    View Slide

  63. View Slide

  64. Contract as
    the source
    of truth

    View Slide

  65. Contract as
    the source
    of truth
    Also a key
    communication
    element!

    View Slide

  66. View Slide

  67. Can derive &
    generate useful
    artifacts
    Client SDKs Server skeletons
    Static, dynamic,
    live mocks
    Test stubs
    Sandbox & live
    playgrounds
    Static
    documentation
    Documentation
    portal

    View Slide

  68. View Slide

  69. Facilitate
    team
    collaboration

    View Slide

  70. !
    "

    View Slide

  71. !
    "
    Backend
    team
    Frontend
    team

    View Slide

  72. !
    "
    Backend
    team
    Frontend
    team

    View Slide

  73. !
    "
    Backend
    team
    Frontend
    team

    View Slide

  74. !
    "
    Backend
    team
    Frontend
    team
    Collaborate
    on contract
    Contract ready,
    mock generated

    View Slide

  75. !
    "
    Backend
    team
    Frontend
    team
    Collaborate
    on contract
    Contract ready,
    mock generated
    Yay! Shorter
    time to market!

    View Slide

  76. View Slide

  77. Code generation
    can overwrite
    customization

    View Slide

  78. Code generation
    can overwrite
    customization
    Favor composition
    over inheritance!

    View Slide

  79. @glaforge
    29
    Pros and cons

    View Slide

  80. @glaforge
    29
    Pros and cons
    Contract as
    the source
    of truth

    View Slide

  81. @glaforge
    29
    Pros and cons
    Contract as
    the source
    of truth
    Facilitate
    team
    collaboration

    View Slide

  82. @glaforge
    29
    Pros and cons
    Contract as
    the source
    of truth
    Facilitate
    team
    collaboration
    Can derive &
    generate useful
    artifacts

    View Slide

  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

    View Slide

  84. TEST-first

    View Slide

  85. @glaforge
    31
    Test Driven Development
    RED

    View Slide

  86. @glaforge
    31
    Test Driven Development
    RED
    GREEN

    View Slide

  87. @glaforge
    31
    Test Driven Development
    RED
    GREEN
    REFACTOR

    View Slide

  88. @glaforge
    31
    Test Driven Development
    RED
    GREEN
    REFACTOR

    View Slide

  89. @glaforge
    Demo: DHC by Restlet

    View Slide

  90. View Slide

  91. Behavior driven:
    clarifies how the
    API is working

    View Slide

  92. View Slide

  93. Can ensure API
    implementation
    and behavior
    are in sync

    View Slide

  94. View Slide

  95. Harder to derive
    & generate
    useful artifacts

    View Slide

  96. Harder to derive
    & generate
    useful artifacts
    Not impossible, but
    not available yet

    View Slide

  97. View Slide

  98. Hard to define
    tests without
    anything to test

    View Slide

  99. Hard to define
    tests without
    anything to test
    Mitigation:
    Solutions with live mocks
    can ease authoring tests
    for defining the behavior

    View Slide

  100. @glaforge
    37
    Pros and cons

    View Slide

  101. @glaforge
    37
    Pros and cons
    Behavior driven:
    clarifies how the
    API is working

    View Slide

  102. @glaforge
    37
    Pros and cons
    Behavior driven:
    clarifies how the
    API is working
    Harder to derive
    & generate
    useful artifacts

    View Slide

  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

    View Slide

  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

    View Slide

  105. DOC-first

    View Slide

  106. @glaforge
    Demo: Silk

    View Slide

  107. View Slide

  108. Use case
    driven, great
    for onboarding

    View Slide

  109. View Slide

  110. Doesn’t necessarily
    generate a useful
    contract

    View Slide

  111. ORANGE

    View Slide

  112. Natural
    language is
    ambiguous
    ORANGE

    View Slide

  113. @glaforge
    43
    Pros and cons

    View Slide

  114. @glaforge
    43
    Pros and cons
    Use case
    driven, great
    for onboarding

    View Slide

  115. @glaforge
    43
    Pros and cons
    Use case
    driven, great
    for onboarding
    Doesn’t necessarily
    generate a useful
    contract

    View Slide

  116. @glaforge
    43
    Pros and cons
    Use case
    driven, great
    for onboarding
    Doesn’t necessarily
    generate a useful
    contract
    Natural
    language is
    ambiguous

    View Slide

  117. @glaforge
    Summary

    View Slide

  118. @glaforge
    45
    Five-sided prism polarizing APIs development
    API
    prism
    CONTRACT DATA
    CODE
    DOC
    TEST

    View Slide

  119. @glaforge
    45
    Five-sided prism polarizing APIs development
    API
    prism
    CONTRACT DATA
    CODE
    DOC
    TEST

    View Slide

  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!

    View Slide

  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!

    View Slide

  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!

    View Slide

  123. @glaforge
    Thanks for your attention

    View Slide

  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

    View Slide

  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

    View Slide

  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

    View Slide