![Page 1: Your API Spec isn’t worth The Paper It’s Written On @nordicAPIS … · 2019. 10. 28. · YOUR API SPEC ISN’T WORTH THE PAPER IT’S WRITTEN ON @APIWORLD 2019 SAN JOSE GARETH](https://reader033.vdocuments.us/reader033/viewer/2022052100/6039efad6df43e69040ba426/html5/thumbnails/1.jpg)
YOUR API SPEC ISN’T WORTH THE PAPER IT’S WRITTEN ON
@APIWORLD 2019 SAN JOSE
GARETH JONES
PRINCIPAL API ARCHITECT
@GARETHJ_MSFT
This Photo by Unknown Author is licensed under CC BY-SA
![Page 2: Your API Spec isn’t worth The Paper It’s Written On @nordicAPIS … · 2019. 10. 28. · YOUR API SPEC ISN’T WORTH THE PAPER IT’S WRITTEN ON @APIWORLD 2019 SAN JOSE GARETH](https://reader033.vdocuments.us/reader033/viewer/2022052100/6039efad6df43e69040ba426/html5/thumbnails/2.jpg)
YOU ARE AN API OWNER. YOU ARE FEELING SMUG.
Open API 3.0 description
Generated SDKs
Automated tests
Pervasive monitoring
This Photo by Unknown Author is licensed under CC BY-SA-NC
![Page 3: Your API Spec isn’t worth The Paper It’s Written On @nordicAPIS … · 2019. 10. 28. · YOUR API SPEC ISN’T WORTH THE PAPER IT’S WRITTEN ON @APIWORLD 2019 SAN JOSE GARETH](https://reader033.vdocuments.us/reader033/viewer/2022052100/6039efad6df43e69040ba426/html5/thumbnails/3.jpg)
YOU DEPLOY A NEW BUILD
This Photo by Unknown Author is licensed under CC BY-NC-ND
This Photo by Unknown Author is licensed under CC BY-NC This Photo by Unknown Author is licensed under CC BY-SA-NC
![Page 4: Your API Spec isn’t worth The Paper It’s Written On @nordicAPIS … · 2019. 10. 28. · YOUR API SPEC ISN’T WORTH THE PAPER IT’S WRITTEN ON @APIWORLD 2019 SAN JOSE GARETH](https://reader033.vdocuments.us/reader033/viewer/2022052100/6039efad6df43e69040ba426/html5/thumbnails/4.jpg)
CONSUMER/PRODUCER CONTRACT
This Photo by Unknown Author is licensed under CC BY-SA
![Page 5: Your API Spec isn’t worth The Paper It’s Written On @nordicAPIS … · 2019. 10. 28. · YOUR API SPEC ISN’T WORTH THE PAPER IT’S WRITTEN ON @APIWORLD 2019 SAN JOSE GARETH](https://reader033.vdocuments.us/reader033/viewer/2022052100/6039efad6df43e69040ba426/html5/thumbnails/5.jpg)
UNDERSPECIFIED CONTRACT
This Photo by Unknown Author is licensed under CC BY
![Page 6: Your API Spec isn’t worth The Paper It’s Written On @nordicAPIS … · 2019. 10. 28. · YOUR API SPEC ISN’T WORTH THE PAPER IT’S WRITTEN ON @APIWORLD 2019 SAN JOSE GARETH](https://reader033.vdocuments.us/reader033/viewer/2022052100/6039efad6df43e69040ba426/html5/thumbnails/6.jpg)
BREAKING CHANGES
This Photo by Unknown Author is licensed under CC BY-NC-ND
![Page 7: Your API Spec isn’t worth The Paper It’s Written On @nordicAPIS … · 2019. 10. 28. · YOUR API SPEC ISN’T WORTH THE PAPER IT’S WRITTEN ON @APIWORLD 2019 SAN JOSE GARETH](https://reader033.vdocuments.us/reader033/viewer/2022052100/6039efad6df43e69040ba426/html5/thumbnails/7.jpg)
DESIGN YOUR BREAKING CHANGE BAR
@garethj_msft
![Page 8: Your API Spec isn’t worth The Paper It’s Written On @nordicAPIS … · 2019. 10. 28. · YOUR API SPEC ISN’T WORTH THE PAPER IT’S WRITTEN ON @APIWORLD 2019 SAN JOSE GARETH](https://reader033.vdocuments.us/reader033/viewer/2022052100/6039efad6df43e69040ba426/html5/thumbnails/8.jpg)
HYRUM’S LAW
With a sufficient number of users of an API,
it does not matter what you promise in the
contract:
all observable behaviors of your system
will be depended on by somebody.
![Page 9: Your API Spec isn’t worth The Paper It’s Written On @nordicAPIS … · 2019. 10. 28. · YOUR API SPEC ISN’T WORTH THE PAPER IT’S WRITTEN ON @APIWORLD 2019 SAN JOSE GARETH](https://reader033.vdocuments.us/reader033/viewer/2022052100/6039efad6df43e69040ba426/html5/thumbnails/9.jpg)
NUMBER OF THINGS GROWS
• Array size grows from 0 to 1
• Array size grows from 1 to n
• Array size grows from < 1 page to >
1 page
This Photo by Unknown Author is licensed under CC BY-SA
![Page 10: Your API Spec isn’t worth The Paper It’s Written On @nordicAPIS … · 2019. 10. 28. · YOUR API SPEC ISN’T WORTH THE PAPER IT’S WRITTEN ON @APIWORLD 2019 SAN JOSE GARETH](https://reader033.vdocuments.us/reader033/viewer/2022052100/6039efad6df43e69040ba426/html5/thumbnails/10.jpg)
SIZES OF THINGS GROW
Image sizes get big
Overall packet sizes get too big
Example: major retailer 10mb packet
Android device can’t handle it with some json stacks
![Page 11: Your API Spec isn’t worth The Paper It’s Written On @nordicAPIS … · 2019. 10. 28. · YOUR API SPEC ISN’T WORTH THE PAPER IT’S WRITTEN ON @APIWORLD 2019 SAN JOSE GARETH](https://reader033.vdocuments.us/reader033/viewer/2022052100/6039efad6df43e69040ba426/html5/thumbnails/11.jpg)
PERFORMANCE, UP DOWN
Lower or higher latency
New race conditions
Higher latency
Unresponsive UI
Batch exceeds acceptable timeframe
This Photo by Unknown Author is licensed under CC BY
![Page 12: Your API Spec isn’t worth The Paper It’s Written On @nordicAPIS … · 2019. 10. 28. · YOUR API SPEC ISN’T WORTH THE PAPER IT’S WRITTEN ON @APIWORLD 2019 SAN JOSE GARETH](https://reader033.vdocuments.us/reader033/viewer/2022052100/6039efad6df43e69040ba426/html5/thumbnails/12.jpg)
DREADED AUTH CHANGES
This Photo by Unknown Author is licensed under CC BY-SA
![Page 13: Your API Spec isn’t worth The Paper It’s Written On @nordicAPIS … · 2019. 10. 28. · YOUR API SPEC ISN’T WORTH THE PAPER IT’S WRITTEN ON @APIWORLD 2019 SAN JOSE GARETH](https://reader033.vdocuments.us/reader033/viewer/2022052100/6039efad6df43e69040ba426/html5/thumbnails/13.jpg)
WEBHOOK DENSITY CHANGES
This Photo by Unknown Author is licensed under CC BY-SA
![Page 14: Your API Spec isn’t worth The Paper It’s Written On @nordicAPIS … · 2019. 10. 28. · YOUR API SPEC ISN’T WORTH THE PAPER IT’S WRITTEN ON @APIWORLD 2019 SAN JOSE GARETH](https://reader033.vdocuments.us/reader033/viewer/2022052100/6039efad6df43e69040ba426/html5/thumbnails/14.jpg)
HYPERMEDIA DOMAIN CHANGES
This Photo by Unknown Author is licensed under CC BY-SA-NC
![Page 15: Your API Spec isn’t worth The Paper It’s Written On @nordicAPIS … · 2019. 10. 28. · YOUR API SPEC ISN’T WORTH THE PAPER IT’S WRITTEN ON @APIWORLD 2019 SAN JOSE GARETH](https://reader033.vdocuments.us/reader033/viewer/2022052100/6039efad6df43e69040ba426/html5/thumbnails/15.jpg)
QUERY PARAMETER COMBO MOVES
This Photo by Unknown Author is licensed under CC BY-SA
![Page 16: Your API Spec isn’t worth The Paper It’s Written On @nordicAPIS … · 2019. 10. 28. · YOUR API SPEC ISN’T WORTH THE PAPER IT’S WRITTEN ON @APIWORLD 2019 SAN JOSE GARETH](https://reader033.vdocuments.us/reader033/viewer/2022052100/6039efad6df43e69040ba426/html5/thumbnails/16.jpg)
HOW CAN WE PROTECT OURSELVES?
![Page 17: Your API Spec isn’t worth The Paper It’s Written On @nordicAPIS … · 2019. 10. 28. · YOUR API SPEC ISN’T WORTH THE PAPER IT’S WRITTEN ON @APIWORLD 2019 SAN JOSE GARETH](https://reader033.vdocuments.us/reader033/viewer/2022052100/6039efad6df43e69040ba426/html5/thumbnails/17.jpg)
PROVIDE A CHAOS MOCK ENDPOINT STRETCH EVERY BOUNDARY CASE
This Photo by Unknown Author is licensed under CC BY
![Page 18: Your API Spec isn’t worth The Paper It’s Written On @nordicAPIS … · 2019. 10. 28. · YOUR API SPEC ISN’T WORTH THE PAPER IT’S WRITTEN ON @APIWORLD 2019 SAN JOSE GARETH](https://reader033.vdocuments.us/reader033/viewer/2022052100/6039efad6df43e69040ba426/html5/thumbnails/18.jpg)
RANDOMLY DISOBEY CONSUMER PREFERENCES
This Photo by Unknown Author is licensed under CC BY
![Page 19: Your API Spec isn’t worth The Paper It’s Written On @nordicAPIS … · 2019. 10. 28. · YOUR API SPEC ISN’T WORTH THE PAPER IT’S WRITTEN ON @APIWORLD 2019 SAN JOSE GARETH](https://reader033.vdocuments.us/reader033/viewer/2022052100/6039efad6df43e69040ba426/html5/thumbnails/19.jpg)
WATCH THOSE LOGS AFTER A DEPLOYMENT
This Photo by Unknown Author is licensed under CC BY
![Page 20: Your API Spec isn’t worth The Paper It’s Written On @nordicAPIS … · 2019. 10. 28. · YOUR API SPEC ISN’T WORTH THE PAPER IT’S WRITTEN ON @APIWORLD 2019 SAN JOSE GARETH](https://reader033.vdocuments.us/reader033/viewer/2022052100/6039efad6df43e69040ba426/html5/thumbnails/20.jpg)
CONSIDER THESE CASES AS BREAKING CHANGES
This Photo by Unknown Author is licensed under CC BY-NC-ND
![Page 21: Your API Spec isn’t worth The Paper It’s Written On @nordicAPIS … · 2019. 10. 28. · YOUR API SPEC ISN’T WORTH THE PAPER IT’S WRITTEN ON @APIWORLD 2019 SAN JOSE GARETH](https://reader033.vdocuments.us/reader033/viewer/2022052100/6039efad6df43e69040ba426/html5/thumbnails/21.jpg)
Oh, one last thing…
21
![Page 22: Your API Spec isn’t worth The Paper It’s Written On @nordicAPIS … · 2019. 10. 28. · YOUR API SPEC ISN’T WORTH THE PAPER IT’S WRITTEN ON @APIWORLD 2019 SAN JOSE GARETH](https://reader033.vdocuments.us/reader033/viewer/2022052100/6039efad6df43e69040ba426/html5/thumbnails/22.jpg)
THANK YOU @garethj_msft