Given at DevXCon SF 2018. Another version focused on technical writers was given at API the Docs Paris 2018.
Having an OpenAPI Specification (OAS) is a useful document for improving the developer experience of an API. The most common use case being the ease of generating API reference documentation, but it overshadows some additional benefits that you can gain from adopting the OpenAPI Specification. This talk will delve into the hidden value of the OpenAPI Specification, and how you can employ it to your advantage.
Some topics include: Design-first APIs, Mocking, Feedback Loops, Testing, and more.
7. "OpenAPI is a bridge to understanding
and being able to communicate around
using HTTP as a transport, and our
greatest hope for helping [people] learn
their HTTPs and 123s."
-Kin Lane, API Evangelist
Photo by Jonas Verstuyft
9. IT IS not JUST FOR API
REFERENCES !
@taylor_atx
10. IT IS not JUST FOR API REFERENCES
▸ Development contract
▸ Prototyping and mocking
▸ Client SDKs and libraries
▸ Testing
▸ Server stubs
@taylor_atx
11. YOU GET TO FOCUS ON
THE good stuff !
@taylor_atx
20. IF YOU WRITE DOCS, TUTORIALS, AND CONTENT, YOU CAN...
▸ Start writing sooner
▸ Give feedback
▸ Have more interactive docs
@taylor_atx
21. IF YOU MAINTAIN CLIENT LIBRARIES OR SDKS, YOU CAN...
▸ More options
▸ Create libraries and SDKs faster
▸ Have libraries ready at release
@taylor_atx
22. IF YOU CARE ABOUT DX, API DESIGN, ADVOCATE FOR USERS,
YOU CAN...
▸ Power feedback loops with mocking
▸ Put real endpoints in front of users
▸ Go look up "API Design Using Feedback Loops," by Lorinda Brandon
▸ "Experimental APIs"
@taylor_atx
23. "Experimental APIs are mock services that use simulated
data to mimic API functions. They are designed with the
goal of getting early feedback from the community around
API desirability and design before the product release."
-Capital One DevExchange, "Design Thinking and API Design"
@taylor_atx
24. MOCKING
▸ Start with humans
▸ "What are the tasks users want to accomplish?"
▸ "Will the API help them achieve these tasks?"
▸ "Are the endpoints confusing?"
@taylor_atx
25. SOME OF THE COMPANIES WITH PUBLIC OPENAPI SPECIFICATIONS
ON GITHUB
SendGrid (16 contributors), Azure (440 contributors),
Slack, Stripe, NY Times, Flickr,
Box, Adafruit, Kubernetes, Nexmo,
Lufthansa, Netlify
@taylor_atx