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.

C74bdcd3fa7c3d3f23290f46430b1463?s=128

Mehdi Lahmam B.

December 11, 2019
Tweet

Transcript

  1. WHO HAS EVER READ AN API DOC?

  2. WHO HAS EVER WRITTEN AN API DOC?

  3. WHO HAS EVER LOVED WRITING AN API DOC?

  4. Mehdi Lahmam @mehlah 4

  5. NO ONE LOVES WRITING API DOCS

  6. BUT EVERYONE WANTS GOOD API DOCS

  7. REMEMBER WHEN WE CHALLENGED THE VALUE OF WRITING TESTS? AND

    HOW MUCH TIME IT TAKES?
  8. THE FIRST TIME I ASKED A CTO TO TAKE TIME

    FOR TESTS ✋
  9. None
  10. TODAY, WE HAVE SOME DECENT TOOLS FOR TESTING

  11. FOR APIS, THE STORY IS A BIT DIFFERENT

  12. PUBLIC APIS DOCS ARE A MARKETING TOOL

  13. AND MARKETING IS RICH

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

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

    TOOL.
  16. WHO CARES?

  17. SOME HAVE TRIED

  18. BLUEPRINT, RAML, PRS, WIKIS, SLACK DMS, AT THE COFFEE MACHINE…

    OR SOMETIMES NEVER !
  19. None
  20. IT’S A GROWING PROBLEM

  21. INSTEAD OF HAVING ONLY 1 API TO DEAL WITH, WE

    INVENTED MICRO SERVICES™
  22. WE ARE DOOMED

  23. WHY THEY’VE FAILED?

  24. IT’S NOT ONLY ABOUT DOCS

  25. IT’S ABOUT DOCS

  26. IT’S ABOUT UPFRONT DESIGN

  27. IT’S ABOUT CHANGES COMMUNICATION AND ANNOUNCEMENTS

  28. IT’S ABOUT CHANGES CONTINUOUS TEST AND VALIDATION

  29. IT’S ABOUT API CLIENTS NOT LAGGING BEHIND

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

  31. API SPECIFICATIONS FTW✌

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

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

  34. None
  35. None
  36. None
  37. None
  38. None
  39. None
  40. I STILL HAVE TO WRITE IT

  41. I CAN DO SO MUCH WITH IT

  42. TOOLS!

  43. EDITORS Vim, VSCode, Atom, <your favorite one> extensions for validation,

    linting, intellisense, …
  44. OPENAPI-GUI

  45. SPOTLIGHT STUDIO ❤

  46. SWAGGER EDITOR

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

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

    ReDoc
  49. None
  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)
  51. MOCK SERVERS Prism, github.com/stoplightio/prism APISprout, github.com/danielgtaylor/apisprout

  52. TESTING Postman OpenAPI JSON Schema conversion

  53. None
  54. None
  55. CLIENTS GENERATION OpenAPI Generator

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

    Trask
  57. WHAT ABOUT NON RESTFUL APIS?

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

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

  60. None
  61. None
  62. None
  63. None
  64. TOOLS!

  65. ASYNCAPI.COM/DOCS/ TOOLING/

  66. VALIDATION You’d like to validate in real-time your Kafka messages?

    asyncapi.stream got you covered!
  67. None
  68. THAT’S NICE, NOW HOW TO MAKE IT EVEN NICER?

  69. SPECIFICATIONS AS CONTRACTS

  70. A SPEC FIRST WORKFLOW

  71. 1. DISCUSS THE DESIGN

  72. 2. WRITE THE SPEC

  73. 3. GENERATE DOCS AND MOCK API

  74. 4. REFINE THE SPEC

  75. 5. USE IT IN TESTS

  76. 6. WRITE THE ACTUAL CODE

  77. None
  78. 7. PUSH THE CODE

  79. 8. CI RUNS

  80. 8. CI RUNS VALIDATE THE SPEC,

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

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

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

    AND NOTIFY ABOUT THE CHANGES
  84. None
  85. None
  86. BENEFITS

  87. SINGLE SOURCE OF TRUTH

  88. DOCUMENTATION AND TESTS ALWAYS UP TO DATE

  89. BETTER WORKFLOWS BETWEEN THE BACKEND AND THE CLIENTS

  90. BACKEND IS AGAIN THE FRONTEND FRIEND

  91. THANKS