A presentation at DevFest Nantes 2021 in in Nantes, France by Sébastien Charrier
API SPECIFICATIONS & CONTRACTS
WHO HAS EVER READ AN API DOC?
WHO HAS EVER WRITTEN AN API DOC?
WHO HAS EVER LOVED WRITING AN API DOC?
Sébastien Charrier @scharrier https://bump.sh
IN A PERFECT WORLD WE SHOULDN’T HAVE TO READ API DOCS,
WE SHOULDN’T HAVE TO WRITE CODE TO CONSUME APIS.
BUT TODAY, APIS ARE STILL USED BY HUMANS 🙋
REMEMBER WHEN WE CHALLENGED THE VALUE OF WRITING TESTS? AND HOW MUCH TIME IT TAKES?
THE FIRST TIME I ASKED MY CEO TO TAKE TIME FOR TESTS ✋
TODAY, FOR MOST OF US, TESTING CODE IS JUST PART OF THE JOB.
FOR APIS DOCS, THE STORY IS A BIT DIFFERENT
PUBLIC APIS DOCS ARE A MARKETING TOOL
AND MARKETING IS RICH💰
MARKETING PEOPLE INVEST IN IT WITH TECHNICAL WRITERS, GREATS DESIGNS AND CUSTOM TOOLS
PRIVATE APIS DOCS AREN’T A MARKETING TOOL, BUT A DEV TOOL.
WHO CARES?
OUTDATED DOCS, HARD TO FIND, MISSING PARTS, BROKEN EXAMPLES…
AND SOMETIMES, NO DOC AT ALL.
AND IT’S NOT THE ONLY PROBLEM 😬
INSTEAD OF HAVING ONLY 1 API TO DEAL WITH, WE INVENTED MICRO SERVICES™ 😎
WE ARE DOOMED
PRS, WIKIS, SLACK, MEETINGS, AT THE COFFEE MACHINE…
WHY DO WE ALWAYS FAIL?
BECAUSE IT’S NOT ONLY ABOUT DOCS.
IT’S ABOUT DESIGN
IT’S ABOUT KNOWLEDGE
IT’S ABOUT CHANGES COMMUNICATION AND PROPAGATION
IT’S ABOUT CONTINUOUS TEST AND VALIDATION
IT’S ABOUT SYNCHRONIZING A WHOLE ECOSYSTEM AROUND THE API.
API SPECIFICATIONS FTW✌
« AN API SPECIFICATION PROVIDES A BROAD UNDERSTANDING OF HOW AN API BEHAVES AND HOW THE API LINKS WITH OTHER APIS. IT EXPLAINS HOW THE API FUNCTIONS AND THE RESULTS TO EXPECT WHEN USING THE API » https://swagger.io/resources/articles/difference-between-api-documentation-specification/
n o i t i n i f e d « AN API SPECIFICATION PROVIDES A BROAD UNDERSTANDING OF HOW AN API BEHAVES AND HOW THE API LINKS WITH OTHER APIS. IT EXPLAINS HOW THE API FUNCTIONS AND THE RESULTS TO EXPECT WHEN USING THE API » https://swagger.io/resources/articles/difference-between-api-documentation-specification/
THE REST API SPECIFICATIONS BATTLE BLUEPRINT ⚡ RAML⚡ OPENAPI
OPENAPI 💪 PREVIOUSLY KNOWN AS SWAGGER https://spec.openapis.org/oas/v3.1.0.html
JSON / YAML
🎁
🎁
HOW DO WE WRITE IT?
CODE FIRST VS DESIGN FIRST
GENERATORS FROM CODE Exist for all languages, all frameworks.
EDITORS Vim, VSCode, Atom, <your favorite one> extensions for validation, linting, intellisense, … Specific editors, like Stoplight Studio or Insomnia.
STOPLIGHT STUDIO ❤
INSOMNIA
A LOT OF TOOLS
DOCS ReDoc Swagger UI Widdershins + Slate or Shins.js SaaS tools like Stoplight, Readme or Bump.sh
LINTERS more than just a linter Spectral, github.com/stoplightio/spectral OpenAPI validator, https://github.com/IBM/openapi-validator
MOCKING Microcks, https://microcks.io/ Prism, github.com/stoplightio/prism
TESTING Microcks (again) ❤ Postman Your unit/integration tests
CLIENTS GENERATION OpenAPI Generator
CHANGE MANAGEMENT OpenAPI-diff Akita Optic Bump.sh
🎁 OPENAPI.TOOLS 200+ curated tools thanks to Phil Sturgeon and Matthew Trask
WHAT ABOUT NON RESTFUL APIS?
GRAPHQL GRPC SOAP ?
EVENT DRIVEN APIS Websockets, AMQP, Kafka, MQTT, etc…
ASYNCAPI TO THE RESCUE* *2016
BASED ON OPENAPI IDEAS, BUT FOR EVENT-BASED APIS
YOU WILL GLOBALLY FIND THE SAME KIND OF TOOLS AS FOR OPENAPI
ASYNCAPI.COM/DOCS/ COMMUNITY/TOOLING
THAT’S NICE, NOW HOW TO MAKE IT EVEN NICER?
f e d s n o i t ini SPECIFICATIONS AS CONTRACTS 🤝
A DESIGN FIRST WORKFLOW
(PLEASE USE DESIGN GUIDELINES)
GOTO 1.
NOW, YOU HAVE A SINGLE SOURCE OF TRUTH,
DOCUMENTATION, TESTS AND CLIENTS ARE ALWAYS UP TO DATE,
AND YOU GET BETTER WORKFLOWS BETWEEN ALL THE HUMANS INVOLVED 🤗
THANKS 😗
Get some swag by contributing to our user research / sebastien@bump.sh
for free. You
can too.