OpenAPI and AsyncAPI specifications as contracts

A presentation at Api Days Paris in December 2019 in Paris, France by Mehdi Lahmam

Slide 1

Slide 1

WHO HAS EVER READ AN API DOC?

Slide 2

Slide 2

WHO HAS EVER WRITTEN AN API DOC?

Slide 3

Slide 3

WHO HAS EVER LOVED WRITING AN API DOC?

Slide 4

Slide 4

Mehdi Lahmam @mehlah 4

Slide 5

Slide 5

NO ONE LOVES WRITING API DOCS

Slide 6

Slide 6

BUT EVERYONE WANTS GOOD API DOCS

Slide 7

Slide 7

REMEMBER WHEN WE CHALLENGED THE VALUE OF WRITING TESTS? AND HOW MUCH TIME IT TAKES?

Slide 8

Slide 8

THE FIRST TIME I ASKED A CTO TO TAKE TIME FOR TESTS ✋

Slide 9

Slide 9

Slide 10

Slide 10

TODAY, WE HAVE SOME DECENT TOOLS FOR TESTING

Slide 11

Slide 11

FOR APIS, THE STORY IS A BIT DIFFERENT

Slide 12

Slide 12

PUBLIC APIS DOCS ARE A MARKETING TOOL

Slide 13

Slide 13

AND MARKETING IS RICH💰

Slide 14

Slide 14

MARKETING PEOPLE INVEST ON IT WITH TECHNICAL WRITERS, GREATS DESIGNS AND CUSTOM TOOLS

Slide 15

Slide 15

PRIVATE APIS DOCS AREN’T A MARKETING TOOL, BUT A DEV TOOL.

Slide 16

Slide 16

WHO CARES?

Slide 17

Slide 17

SOME HAVE TRIED

Slide 18

Slide 18

BLUEPRINT, RAML, PRS, WIKIS, SLACK DMS, AT THE COFFEE MACHINE… OR SOMETIMES NEVER !

Slide 19

Slide 19

Slide 20

Slide 20

IT’S A GROWING PROBLEM 😬

Slide 21

Slide 21

INSTEAD OF HAVING ONLY 1 API TO DEAL WITH, WE INVENTED MICRO SERVICES™ 😎

Slide 22

Slide 22

WE ARE DOOMED

Slide 23

Slide 23

WHY THEY’VE FAILED?

Slide 24

Slide 24

IT’S NOT ONLY ABOUT DOCS

Slide 25

Slide 25

IT’S ABOUT DOCS

Slide 26

Slide 26

IT’S ABOUT UPFRONT DESIGN

Slide 27

Slide 27

IT’S ABOUT CHANGES COMMUNICATION AND ANNOUNCEMENTS

Slide 28

Slide 28

IT’S ABOUT CHANGES CONTINUOUS TEST AND VALIDATION

Slide 29

Slide 29

IT’S ABOUT API CLIENTS NOT LAGGING BEHIND

Slide 30

Slide 30

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

Slide 31

Slide 31

API SPECIFICATIONS FTW✌

Slide 32

Slide 32

TONY TAM INVENTED SWAGGER A LOOOOONG TIME AGO* *2011

Slide 33

Slide 33

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

Slide 34

Slide 34

Slide 35

Slide 35

Slide 36

Slide 36

Slide 37

Slide 37

Slide 38

Slide 38

Slide 39

Slide 39

Slide 40

Slide 40

I STILL HAVE TO WRITE IT 😩

Slide 41

Slide 41

I CAN DO SO MUCH WITH IT 🥳

Slide 42

Slide 42

TOOLS!

Slide 43

Slide 43

EDITORS Vim, VSCode, Atom, <your favorite one> extensions for validation, linting, intellisense, …

Slide 44

Slide 44

OPENAPI-GUI

Slide 45

Slide 45

SPOTLIGHT STUDIO ❤

Slide 46

Slide 46

SWAGGER EDITOR

Slide 47

Slide 47

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

Slide 48

Slide 48

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

Slide 49

Slide 49

Slide 50

Slide 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)

Slide 51

Slide 51

MOCK SERVERS Prism, github.com/stoplightio/prism APISprout, github.com/danielgtaylor/apisprout

Slide 52

Slide 52

TESTING Postman OpenAPI 🔄 JSON Schema conversion

Slide 53

Slide 53

Slide 54

Slide 54

Slide 55

Slide 55

CLIENTS GENERATION OpenAPI Generator

Slide 56

Slide 56

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

Slide 57

Slide 57

WHAT ABOUT NON RESTFUL APIS?

Slide 58

Slide 58

FRAN MENDEZ TO THE RESCUE WITH ASYNCAPI* *2016

Slide 59

Slide 59

BASED ON OPENAPI IDEAS, BUT FOR EVENT-BASED APIS

Slide 60

Slide 60

Slide 61

Slide 61

Slide 62

Slide 62

Slide 63

Slide 63

Slide 64

Slide 64

TOOLS!

Slide 65

Slide 65

ASYNCAPI.COM/DOCS/ TOOLING/

Slide 66

Slide 66

VALIDATION You’d like to validate in real-time your Kafka messages? asyncapi.stream got you covered!

Slide 67

Slide 67

Slide 68

Slide 68

THAT’S NICE, NOW HOW TO MAKE IT EVEN NICER?

Slide 69

Slide 69

SPECIFICATIONS AS CONTRACTS🤝

Slide 70

Slide 70

A SPEC FIRST WORKFLOW

Slide 71

Slide 71

  1. DISCUSS THE DESIGN

Slide 72

Slide 72

  1. WRITE THE SPEC

Slide 73

Slide 73

  1. GENERATE DOCS AND MOCK API

Slide 74

Slide 74

  1. REFINE THE SPEC

Slide 75

Slide 75

  1. USE IT IN TESTS

Slide 76

Slide 76

  1. WRITE THE ACTUAL CODE 😬

Slide 77

Slide 77

Slide 78

Slide 78

  1. PUSH THE CODE

Slide 79

Slide 79

  1. CI RUNS

Slide 80

Slide 80

  1. CI RUNS VALIDATE THE SPEC,

Slide 81

Slide 81

  1. CI RUNS VALIDATE THE SPEC, UPDATE DOCS,

Slide 82

Slide 82

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

Slide 83

Slide 83

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

Slide 84

Slide 84

Slide 85

Slide 85

Slide 86

Slide 86

💯 BENEFITS

Slide 87

Slide 87

SINGLE SOURCE OF TRUTH

Slide 88

Slide 88

DOCUMENTATION AND TESTS ALWAYS UP TO DATE

Slide 89

Slide 89

BETTER WORKFLOWS BETWEEN THE BACKEND AND THE CLIENTS

Slide 90

Slide 90

BACKEND IS AGAIN THE FRONTEND FRIEND 🤗

Slide 91

Slide 91

THANKS 😗