Summary: Listen to this post: You can download the MP3 file, subscribe in iTunes, or listen with Stitcher. The Design of Web APIs, by Arnaud Lauret Podcast topics Here are some of the API design/usability topics we chat about in the podcast: What API usability is, and how usability is the same/different with developer tools How writing documentation tests the usability of a product What tech writers should look for to know whether an API is designed well What to call each of the components in an API (e.g., whether the term “endpoint” should be used) How tech writers can influence design and usability when they’re so far downstream in the development process Best practices for creating tutorials on API doc sites Spec-first design versus auto-generating the OpenAPI from the code Which framework you would you choose to work with to render the API spec Whether we’ll eventually move into a state where manually editing the OpenAPI spec code by hand becomes antiquated The Open Map visual diagram that shows the OpenAPI structure Recommended APIs that we should learn from and why Why providing the OpenAPI spec is important even if you don’t generate your docs from it How tech writers might interact with their company’s API style/design guide and why Whether the reference content and user guide should be separate or seamless Tip: If you'd like to explore these ideas in more depth, consider getting a copy of The Design of Web APIs. I've read the book and found it relevant and helpful to the work of technical documentation. Resources The Design of Web APIs (book) API style book OpenAPI Map API Handyman blog @apihandyman (Twitter) API Developer Weekly newsletter WebAPI Events DBS Developer Portal Visual Code Studio Swagger Viewer extension openapi-lint extension
