This talk was presented at API The Docs Virtual 2020 event series on 7 October. We are honored to share the video recording, slide deck, and talk summary below. Enjoy!
Visit the API The Docs 2020 recaps overview to explore all presentations this year.
We can go beyond generating API documentation of OpenAPI schemas, but to successfully utilize innovative solutions, you have to follow the path of the API Product lifecycle.
In 2008, REST APIs were rough and based on XML. They seemed simple to implement, but they weren't implemented well, partially because we didn’t have standards well adapted.
Having a schema in Web Application Description Language (WADL) you were able to auto-generate documentation. It was like a standard of how to design REST APIs in XML. WADL didn’t get popular, because using XML was inconvenient.
JSON pushed XML APIs off the scene, and Swagger brought the standard definitions: a schema. Now you can auto-generate RESTful API documentation from a swagger/OpenAPI specification file.
REST APIs became easier to build, fairly consistent, and aggregator tools make it possible to connect APIs.
The failure of Product management, in general, is the philosophy of “If you build it, they will come…”
API Product cycle (CI/CD tech stack): automation to generate good content and make it easier to provide updates to the APIs, API documentation, API libraries, SDKs on the developer portal. To get even the smallest updates automatically reflected, you first have to create a solid design: start with the OpenAPI schema and build from there.
Identify the problem
Research to understand the problem
Implement -- if and after you have the OpenAPI schema
Launch the API and have an elegant Developer experience
Maintain & Iterate
obvious iterations and opportunities