---
title: "Podcast: API Design and Usability with Arnaud Lauret (API Handyman)"
date: 2019-12-07
description: "Podcast topics Resources Listen here: <a..."
canonical_url: https://idratherbewriting.com/blog/api-design-usability-arnaud-lauret-podcast/index.html
---

> For AI agents: a documentation index is available at https://idratherbewriting.com/llms.txt. Markdown versions of all pages are available by appending .md to any page URL.

# Podcast: API Design and Usability with Arnaud Lauret (API Handyman)

> Arnaud Lauret, also known as the API Handyman, recently published a book called [The Design of Web APIs](https://www.manning.com/books/the-design-of-web-apis). In this podcast, I chat with Arnaud about his book, specifically exploring best practices for designing web APIs and focusing on the roles technical writers can play.

**Listen here:**

[Audio](https://dts.podtrac.com/redirect.mp3/s3.us-west-1.wasabisys.com/idbwmedia.com/podcasts/api_design_usability_arnaud.mp3)

[![](https://s3.us-west-1.wasabisys.com/idbwmedia.com/images/apple_podcasts.png)](https://itunes.apple.com/us/podcast/id-rather-be-writing-podcast/id277365275) [![](https://s3.us-west-1.wasabisys.com/idbwmedia.com/images/watchonyoutubeblack.png)](https://www.youtube.com/@idratherbewriting) [![](https://s3.us-west-1.wasabisys.com/idbwmedia.com/images/spotify.png)](https://open.spotify.com/show/4HeOZfPGMMfViOhVS40QBD)

![The Design of Web APIs, by Arnaud Lauret](https://s3.us-west-1.wasabisys.com/idbwmedia.com/images/design-of-web-apis.png)

> **Tip:** See also this topic in my API course: [API design and usability](https://idratherbewriting.com/learnapidoc/evaluating-api-design.html). In this topic, I expand on many of the principles Arnaud discusses in his book.

## 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](https://openapi-map.apihandyman.io/) 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](https://www.manning.com/books/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](https://www.manning.com/books/the-design-of-web-apis) (book)
- [API style book](http://apistylebook.com/)
- [OpenAPI Map](https://openapi-map.apihandyman.io/)
- [API Handyman blog](https://apihandyman.io/)
- [@apihandyman (Twitter)](https://twitter.com/apihandyman?lang=en)
- [API Developer Weekly newsletter](https://apideveloperweekly.com/)
- [WebAPI Events](https://webapi.events/)
- [DBS Developer Portal](https://www.dbs.com/dbsdevelopers/)
- [Visual Code Studio](https://code.visualstudio.com/)
- [Swagger Viewer extension](https://marketplace.visualstudio.com/items?itemName=Arjun.swagger-viewer)
- [openapi-lint extension](https://marketplace.visualstudio.com/items?itemName=mermade.openapi-lint)