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

OpenAPI and AsyncAPI specifications as contracts

OpenAPI and AsyncAPI specifications as contracts

Talk given first at APIDays Paris 2019 on December 11th.

Abstract:
Meet OpenAPI and AsyncAPI, your APIs contracts.
With the growing number of APIs we write, as many problems arise: harder cross-teams communication, poor or outdated internal docs, APIs clients harder to maintain... These problems are even worse with the nature of the modern web and the adoption of (micro)services architectures.
OpenAPI and AsyncAPI specifications has revolutionized the way we design, build, and manage APIs: using them as a tool for continuous management of your APIs as part of your CI, will be one of your best move for 2020.

Mehdi Lahmam B.

December 11, 2019
Tweet

More Decks by Mehdi Lahmam B.

Other Decks in Programming

Transcript

  1. WHO HAS EVER
    READ
    AN API DOC?

    View Slide

  2. WHO HAS EVER
    WRITTEN
    AN API DOC?

    View Slide

  3. WHO HAS EVER
    LOVED WRITING
    AN API DOC?

    View Slide

  4. Mehdi Lahmam
    @mehlah
    4

    View Slide

  5. NO ONE LOVES WRITING
    API DOCS

    View Slide

  6. BUT EVERYONE
    WANTS GOOD API DOCS

    View Slide

  7. REMEMBER WHEN WE
    CHALLENGED THE VALUE
    OF WRITING TESTS?
    AND HOW MUCH TIME IT TAKES?

    View Slide

  8. THE FIRST TIME
    I ASKED A CTO
    TO TAKE TIME
    FOR TESTS ✋

    View Slide

  9. View Slide

  10. TODAY, WE HAVE SOME
    DECENT TOOLS FOR
    TESTING

    View Slide

  11. FOR APIS, THE STORY IS
    A BIT DIFFERENT

    View Slide

  12. PUBLIC APIS DOCS ARE
    A MARKETING TOOL

    View Slide

  13. AND MARKETING IS
    RICH

    View Slide

  14. MARKETING PEOPLE
    INVEST ON IT WITH
    TECHNICAL WRITERS,
    GREATS DESIGNS AND
    CUSTOM TOOLS

    View Slide

  15. PRIVATE APIS DOCS
    AREN’T A MARKETING
    TOOL, BUT A DEV TOOL.

    View Slide

  16. WHO
    CARES?

    View Slide

  17. SOME HAVE TRIED

    View Slide

  18. BLUEPRINT, RAML, PRS,
    WIKIS, SLACK DMS, AT
    THE COFFEE MACHINE…
    OR SOMETIMES NEVER !

    View Slide

  19. View Slide

  20. IT’S A GROWING
    PROBLEM

    View Slide

  21. INSTEAD OF HAVING
    ONLY 1 API TO DEAL
    WITH, WE INVENTED
    MICRO SERVICES™

    View Slide

  22. WE ARE
    DOOMED

    View Slide

  23. WHY THEY’VE FAILED?

    View Slide

  24. IT’S NOT
    ONLY ABOUT DOCS

    View Slide

  25. IT’S ABOUT
    DOCS

    View Slide

  26. IT’S ABOUT
    UPFRONT DESIGN

    View Slide

  27. IT’S ABOUT
    CHANGES
    COMMUNICATION AND
    ANNOUNCEMENTS

    View Slide

  28. IT’S ABOUT
    CHANGES CONTINUOUS
    TEST AND VALIDATION

    View Slide

  29. IT’S ABOUT
    API CLIENTS NOT
    LAGGING BEHIND

    View Slide

  30. IT’S ABOUT A WHOLE
    ECOSYSTEM OF TOOLS
    AROUND THE API

    View Slide

  31. API SPECIFICATIONS
    FTW✌

    View Slide

  32. TONY TAM INVENTED
    SWAGGER A LOOOOONG
    TIME AGO*
    *2011

    View Slide

  33. NOW KNOWN AS
    OPENAPI
    https://spec.openapis.org/oas/v3.0.2

    View Slide

  34. View Slide

  35. View Slide

  36. View Slide

  37. View Slide

  38. View Slide

  39. View Slide

  40. I STILL HAVE TO WRITE
    IT

    View Slide

  41. I CAN DO SO MUCH
    WITH IT

    View Slide

  42. TOOLS!

    View Slide

  43. EDITORS
    Vim, VSCode, Atom, extensions for
    validation, linting, intellisense, …

    View Slide

  44. OPENAPI-GUI

    View Slide

  45. SPOTLIGHT STUDIO ❤

    View Slide

  46. SWAGGER EDITOR

    View Slide

  47. LINTERS
    Speccy, github.com/wework/speccy
    Spectral, github.com/stoplightio/spectral

    View Slide

  48. DOCS
    Swagger UI
    Widdershins + Slate or Shins.js
    Bump, bump.sh
    ReDoc

    View Slide

  49. View Slide

  50. MOCK SERVERS
    Mock HTTP server and respond realistically
    Server validation
    Validation proxy
    Recording / "Learning" mode to create spec files
    Data Persistence (aka sandbox mode)

    View Slide

  51. MOCK SERVERS
    Prism, github.com/stoplightio/prism
    APISprout, github.com/danielgtaylor/apisprout

    View Slide

  52. TESTING
    Postman
    OpenAPI JSON Schema conversion

    View Slide

  53. View Slide

  54. View Slide

  55. CLIENTS GENERATION
    OpenAPI Generator

    View Slide

  56. OPENAPI.TOOLS
    120+ curated tools thanks to
    Phil Sturgeon and Matthew Trask

    View Slide

  57. WHAT ABOUT NON
    RESTFUL APIS?

    View Slide

  58. FRAN MENDEZ TO THE
    RESCUE WITH
    ASYNCAPI*
    *2016

    View Slide

  59. BASED ON OPENAPI
    IDEAS,
    BUT FOR EVENT-BASED
    APIS

    View Slide

  60. View Slide

  61. View Slide

  62. View Slide

  63. View Slide

  64. TOOLS!

    View Slide

  65. ASYNCAPI.COM/DOCS/
    TOOLING/

    View Slide

  66. VALIDATION
    You’d like to validate in real-time your Kafka messages?
    asyncapi.stream got you covered!

    View Slide

  67. View Slide

  68. THAT’S NICE,
    NOW HOW TO MAKE IT
    EVEN NICER?

    View Slide

  69. SPECIFICATIONS AS
    CONTRACTS

    View Slide

  70. A SPEC FIRST
    WORKFLOW

    View Slide

  71. 1. DISCUSS THE DESIGN

    View Slide

  72. 2. WRITE THE SPEC

    View Slide

  73. 3. GENERATE DOCS AND
    MOCK API

    View Slide

  74. 4. REFINE THE SPEC

    View Slide

  75. 5. USE IT IN TESTS

    View Slide

  76. 6. WRITE THE ACTUAL
    CODE

    View Slide

  77. View Slide

  78. 7. PUSH THE CODE

    View Slide

  79. 8. CI RUNS

    View Slide

  80. 8. CI RUNS
    VALIDATE THE SPEC,

    View Slide

  81. 8. CI RUNS
    VALIDATE THE SPEC, UPDATE
    DOCS,

    View Slide

  82. 8. CI RUNS
    VALIDATE THE SPEC, UPDATE
    DOCS, UPDATE CLIENTS

    View Slide

  83. 8. CI RUNS
    VALIDATE THE SPEC, UPDATE
    DOCS, UPDATE CLIENTS AND
    NOTIFY ABOUT THE CHANGES

    View Slide

  84. View Slide

  85. View Slide

  86. BENEFITS

    View Slide

  87. SINGLE SOURCE OF
    TRUTH

    View Slide

  88. DOCUMENTATION AND
    TESTS ALWAYS UP TO
    DATE

    View Slide

  89. BETTER WORKFLOWS
    BETWEEN THE BACKEND
    AND THE CLIENTS

    View Slide

  90. BACKEND IS AGAIN THE
    FRONTEND FRIEND

    View Slide

  91. THANKS

    View Slide