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

  1. DISCUSS THE DESIGN

(PLEASE USE DESIGN GUIDELINES)

  1. EDIT THE CONTRACT COMMIT AND PUSH

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

  1. REFINE THE SPEC UNTIL THE CHANGE IS APPROVED ✅

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

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

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