API specifications and contracts

A presentation at DevFest Nantes 2021 in October 2021 in Nantes, France by Sébastien Charrier

Slide 1

Slide 1

API SPECIFICATIONS & CONTRACTS

Slide 2

Slide 2

WHO HAS EVER READ AN API DOC?

Slide 3

Slide 3

WHO HAS EVER WRITTEN AN API DOC?

Slide 4

Slide 4

WHO HAS EVER LOVED WRITING AN API DOC?

Slide 5

Slide 5

Sébastien Charrier @scharrier https://bump.sh

Slide 6

Slide 6

IN A PERFECT WORLD WE SHOULDN’T HAVE TO READ API DOCS,

Slide 7

Slide 7

WE SHOULDN’T HAVE TO WRITE CODE TO CONSUME APIS.

Slide 8

Slide 8

BUT TODAY, APIS ARE STILL USED BY HUMANS 🙋

Slide 9

Slide 9

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

Slide 10

Slide 10

THE FIRST TIME I ASKED MY CEO TO TAKE TIME FOR TESTS ✋

Slide 11

Slide 11

Slide 12

Slide 12

TODAY, FOR MOST OF US, TESTING CODE IS JUST PART OF THE JOB.

Slide 13

Slide 13

FOR APIS DOCS, THE STORY IS A BIT DIFFERENT

Slide 14

Slide 14

PUBLIC APIS DOCS ARE A MARKETING TOOL

Slide 15

Slide 15

AND MARKETING IS RICH💰

Slide 16

Slide 16

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

Slide 17

Slide 17

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

Slide 18

Slide 18

WHO CARES?

Slide 19

Slide 19

OUTDATED DOCS, HARD TO FIND, MISSING PARTS, BROKEN EXAMPLES…

Slide 20

Slide 20

AND SOMETIMES, NO DOC AT ALL.

Slide 21

Slide 21

AND IT’S NOT THE ONLY PROBLEM 😬

Slide 22

Slide 22

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

Slide 23

Slide 23

WE ARE DOOMED

Slide 24

Slide 24

Slide 25

Slide 25

PRS, WIKIS, SLACK, MEETINGS, AT THE COFFEE MACHINE…

Slide 26

Slide 26

WHY DO WE ALWAYS FAIL?

Slide 27

Slide 27

BECAUSE IT’S NOT ONLY ABOUT DOCS.

Slide 28

Slide 28

IT’S ABOUT DESIGN

Slide 29

Slide 29

IT’S ABOUT KNOWLEDGE

Slide 30

Slide 30

IT’S ABOUT CHANGES COMMUNICATION AND PROPAGATION

Slide 31

Slide 31

IT’S ABOUT CONTINUOUS TEST AND VALIDATION

Slide 32

Slide 32

IT’S ABOUT SYNCHRONIZING A WHOLE ECOSYSTEM AROUND THE API.

Slide 33

Slide 33

API SPECIFICATIONS FTW✌

Slide 34

Slide 34

« 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/

Slide 35

Slide 35

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/

Slide 36

Slide 36

THE REST API SPECIFICATIONS BATTLE BLUEPRINT ⚡ RAML⚡ OPENAPI

Slide 37

Slide 37

OPENAPI 💪 PREVIOUSLY KNOWN AS SWAGGER https://spec.openapis.org/oas/v3.1.0.html

Slide 38

Slide 38

JSON / YAML

Slide 39

Slide 39

🎁

Slide 40

Slide 40

🎁

Slide 41

Slide 41

Slide 42

Slide 42

HOW DO WE WRITE IT?

Slide 43

Slide 43

CODE FIRST VS DESIGN FIRST

Slide 44

Slide 44

GENERATORS FROM CODE Exist for all languages, all frameworks.

Slide 45

Slide 45

EDITORS Vim, VSCode, Atom, <your favorite one> extensions for validation, linting, intellisense, … Specific editors, like Stoplight Studio or Insomnia.

Slide 46

Slide 46

STOPLIGHT STUDIO ❤

Slide 47

Slide 47

INSOMNIA

Slide 48

Slide 48

A LOT OF TOOLS

Slide 49

Slide 49

DOCS ReDoc Swagger UI Widdershins + Slate or Shins.js SaaS tools like Stoplight, Readme or Bump.sh

Slide 50

Slide 50

Slide 51

Slide 51

LINTERS more than just a linter Spectral, github.com/stoplightio/spectral OpenAPI validator, https://github.com/IBM/openapi-validator

Slide 52

Slide 52

MOCKING Microcks, https://microcks.io/ Prism, github.com/stoplightio/prism

Slide 53

Slide 53

TESTING Microcks (again) ❤ Postman Your unit/integration tests

Slide 54

Slide 54

Slide 55

Slide 55

CLIENTS GENERATION OpenAPI Generator

Slide 56

Slide 56

CHANGE MANAGEMENT OpenAPI-diff Akita Optic Bump.sh

Slide 57

Slide 57

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

Slide 58

Slide 58

WHAT ABOUT NON RESTFUL APIS?

Slide 59

Slide 59

GRAPHQL GRPC SOAP ?

Slide 60

Slide 60

EVENT DRIVEN APIS Websockets, AMQP, Kafka, MQTT, etc…

Slide 61

Slide 61

ASYNCAPI TO THE RESCUE* *2016

Slide 62

Slide 62

BASED ON OPENAPI IDEAS, BUT FOR EVENT-BASED APIS

Slide 63

Slide 63

Slide 64

Slide 64

Slide 65

Slide 65

YOU WILL GLOBALLY FIND THE SAME KIND OF TOOLS AS FOR OPENAPI

Slide 66

Slide 66

ASYNCAPI.COM/DOCS/ COMMUNITY/TOOLING

Slide 67

Slide 67

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

Slide 68

Slide 68

f e d s n o i t ini SPECIFICATIONS AS CONTRACTS 🤝

Slide 69

Slide 69

A DESIGN FIRST WORKFLOW

Slide 70

Slide 70

  1. DISCUSS THE DESIGN

Slide 71

Slide 71

Slide 72

Slide 72

(PLEASE USE DESIGN GUIDELINES)

Slide 73

Slide 73

  1. EDIT THE CONTRACT COMMIT AND PUSH

Slide 74

Slide 74

Slide 75

Slide 75

  1. CI RUNS VALIDATE THE CONTRACT (NO BREAKING CHANGES?), GENERATE A DIFF SUMMARY, CREATE A TEMPORARY MOCK SERVER

Slide 76

Slide 76

  1. REFINE THE SPEC UNTIL THE CHANGE IS APPROVED ✅

Slide 77

Slide 77

  1. WRITE THE ACTUAL CODE AND TESTS PUSH, REVIEW, AND MERGE EVERYTHING

Slide 78

Slide 78

  1. CI RUNS AND DEPLOYS DEPLOYS THE CODE, UPDATE DOCS, UPDATE CLIENTS AND NOTIFY ABOUT THE CHANGES

Slide 79

Slide 79

GOTO 1.

Slide 80

Slide 80

NOW, YOU HAVE A SINGLE SOURCE OF TRUTH,

Slide 81

Slide 81

DOCUMENTATION, TESTS AND CLIENTS ARE ALWAYS UP TO DATE,

Slide 82

Slide 82

AND YOU GET BETTER WORKFLOWS BETWEEN ALL THE HUMANS INVOLVED 🤗

Slide 83

Slide 83

THANKS 😗

Slide 84

Slide 84

Get some swag by contributing to our user research / sebastien@bump.sh