A presentation at Api Days Paris in in Paris, France by Mehdi Lahmam
WHO HAS EVER READ AN API DOC?
WHO HAS EVER WRITTEN AN API DOC?
WHO HAS EVER LOVED WRITING AN API DOC?
Mehdi Lahmam @mehlah 4
NO ONE LOVES WRITING API DOCS
BUT EVERYONE WANTS GOOD API DOCS
REMEMBER WHEN WE CHALLENGED THE VALUE OF WRITING TESTS? AND HOW MUCH TIME IT TAKES?
THE FIRST TIME I ASKED A CTO TO TAKE TIME FOR TESTS ✋
TODAY, WE HAVE SOME DECENT TOOLS FOR TESTING
FOR APIS, THE STORY IS A BIT DIFFERENT
PUBLIC APIS DOCS ARE A MARKETING TOOL
AND MARKETING IS RICH💰
MARKETING PEOPLE INVEST ON IT WITH TECHNICAL WRITERS, GREATS DESIGNS AND CUSTOM TOOLS
PRIVATE APIS DOCS AREN’T A MARKETING TOOL, BUT A DEV TOOL.
WHO CARES?
SOME HAVE TRIED
BLUEPRINT, RAML, PRS, WIKIS, SLACK DMS, AT THE COFFEE MACHINE… OR SOMETIMES NEVER !
IT’S A GROWING PROBLEM 😬
INSTEAD OF HAVING ONLY 1 API TO DEAL WITH, WE INVENTED MICRO SERVICES™ 😎
WE ARE DOOMED
WHY THEY’VE FAILED?
IT’S NOT ONLY ABOUT DOCS
IT’S ABOUT DOCS
IT’S ABOUT UPFRONT DESIGN
IT’S ABOUT CHANGES COMMUNICATION AND ANNOUNCEMENTS
IT’S ABOUT CHANGES CONTINUOUS TEST AND VALIDATION
IT’S ABOUT API CLIENTS NOT LAGGING BEHIND
IT’S ABOUT A WHOLE ECOSYSTEM OF TOOLS AROUND THE API
API SPECIFICATIONS FTW✌
TONY TAM INVENTED SWAGGER A LOOOOONG TIME AGO* *2011
NOW KNOWN AS OPENAPI https://spec.openapis.org/oas/v3.0.2
I STILL HAVE TO WRITE IT 😩
I CAN DO SO MUCH WITH IT 🥳
TOOLS!
EDITORS Vim, VSCode, Atom, <your favorite one> extensions for validation, linting, intellisense, …
OPENAPI-GUI
SPOTLIGHT STUDIO ❤
SWAGGER EDITOR
LINTERS Speccy, github.com/wework/speccy Spectral, github.com/stoplightio/spectral
DOCS Swagger UI Widdershins + Slate or Shins.js ReDoc Bump, bump.sh
MOCK SERVERS Mock HTTP server and respond realistically Server validation Validation proxy 🔜 Recording / “Learning” mode to create spec files 🔜 Data Persistence (aka sandbox mode)
MOCK SERVERS Prism, github.com/stoplightio/prism APISprout, github.com/danielgtaylor/apisprout
TESTING Postman OpenAPI 🔄 JSON Schema conversion
CLIENTS GENERATION OpenAPI Generator
🎁 OPENAPI.TOOLS 120+ curated tools thanks to Phil Sturgeon and Matthew Trask
WHAT ABOUT NON RESTFUL APIS?
FRAN MENDEZ TO THE RESCUE WITH ASYNCAPI* *2016
BASED ON OPENAPI IDEAS, BUT FOR EVENT-BASED APIS
TOOLS!
ASYNCAPI.COM/DOCS/ TOOLING/
VALIDATION You’d like to validate in real-time your Kafka messages? asyncapi.stream got you covered!
THAT’S NICE, NOW HOW TO MAKE IT EVEN NICER?
SPECIFICATIONS AS CONTRACTS🤝
A SPEC FIRST WORKFLOW
💯 BENEFITS
SINGLE SOURCE OF TRUTH
DOCUMENTATION AND TESTS ALWAYS UP TO DATE
BETTER WORKFLOWS BETWEEN THE BACKEND AND THE CLIENTS
BACKEND IS AGAIN THE FRONTEND FRIEND 🤗
THANKS 😗
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.
for free. You
can too.