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.
