DESIGn-FIRST APIs
with OPen API Spec (OAS)
nanovazquez.dev
@nanovazquez__





In most projects, the biggest challenge to solve is not technology, it's communication
USEFUL LINKS
Full-stack developer (15+ years)
International speaker
Engineering manager @ MODO
Microsoft MVP & Co-organizer of conferences & meetups
ReactBA, vOpen, DevDayAr



HI! I'm Nano Vazquez



Today's Agenda
#1
Writing your first OAS Document
#2
Implementing your oas API
#3
DEVELOPING API CLIENTS for your consumers
SCENARIO
WHAT WE ARE GOING TO DO



THe team

Use cases


?
200 OK
- List of speakers of any conference
- List of activities of any conference
- The agenda of a conference
- Ability to provide feedback to any activity

Hey, can you send me the docs of your service?


?
200 OK
No docs
Nah, Just use it
CODE AS DOCS
My code doesn't need docs

AD-HOC DOCS
This just came fresh out of the oven


AD-HOC DOCS
No docs
CODE AS DOCS
#1
#2
#3
SUMMARY
is there a better way?
Idea: API Portal

WRITING YOUR FIRST OAS DOCUMENT
Swagger

Swagger is an open source software framework backed by a broad ecosystem of tools that helps developers design, build, document, standardize and consume RESTful Web services.
Automated documentation
Code generation
Test case generation
OAS









Use cases


?
200 OK
- List of speakers of any conference
- List of activities of any conference
- The agenda of a conference
- Ability to provide feedback to any activity
DEMO 1: YOUR FIRST OAS DOC
Swaggerhub

REcap: SWAGGERHUB
web-based editor with autocomplete
#1
#2
#3
Real-time autogenerated API docs
An API Auto Mocking integration
DEMO 2: TEST YOUR API
TEST YOUR API


DEVELOPING
API CLIENTS
CONFIGURE CLIENT SDK

DEMO 3: THE CLIENT SDK
THE clIENT SDK

CLIENT SDK LANGUAGES

30+ languages








CLIENT SDK LIFECYCLE







REcap: Client SDK
AUTOGENERATED LIBRARIES TO SIMPLIFY USAGE
#1
#2
#3
Multiple languages SUPPORTED
DELIVERED VIA PACKAGE MANAGERS
IMPLEMENTING YOUR API
IMPLEMENT AN API

DEMO 4: Server STUB
DOWNLOAD THE SERVER STUB

API DOCUMENTATION

SUMMARY
#1
WRITE YOUR OAS DOCUMENT FIRST
#2
PROFIT!
#3
GET CLIENT SDK, docs AND SERVER STUB FOr free
well... no, implement it :D
enabling others to code right away

Twitter: @nanovazquez__
THANKS!
Design-first APIs with OAS
By Mariano Vazquez
Design-first APIs with OAS
Ready to learn new stuff? If you are modeling APIs using Google docs, this talk IS FOR YOU. You’ll learn how to design your APIs from scratch with OAS, and all the bonuses you could get without adding a single line of code: a mocked service, autogenerated code & docs, API testing, etc.
- 1,609