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.

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