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

  1. DISCUSS THE DESIGN

  1. WRITE THE SPEC

  1. GENERATE DOCS AND MOCK API

  1. REFINE THE SPEC

  1. USE IT IN TESTS

  1. WRITE THE ACTUAL CODE 😬

  1. PUSH THE CODE

  1. CI RUNS

  1. CI RUNS VALIDATE THE SPEC,

  1. CI RUNS VALIDATE THE SPEC, UPDATE DOCS,

  1. CI RUNS VALIDATE THE SPEC, UPDATE DOCS, UPDATE CLIENTS

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

💯 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 😗