Thoughts on API Design low-fidelity mockups

I recently asked a question" on twitter:

What’s the analog of a low-fidelity mockup for API Design? What tool would you use? Why would it be useful?

I wasn’t expecting much. However, I received a bunch of replies. Most people focused on answering what they’re using for API Design, and not necessarily for doing low-fidelity mockups. Here’s a list of ideas that people shared:

• Darrel Mirrel shares that he uses Mermaid graph diagrams to design and describe resource URLs.
• Erik Wilde writes that he starts with something he calls “API stories.” Those stories inform Erik of the experience that users have while interacting with the API. After figuring out what those stories are, Erik defines how the API will work.
• Heimo Laukkanen explains that he starts by drafting endpoint URLs and descriptions using a Markdown document. He then uses Stoplight mocking to make sense of the API experience before writing any code.
• Luca Ferrari shares that he starts with simple user stories to identify possible endpoints, objects, and interactions.
• Oscar Islas says (in Spanish) that he creates an API mock that always returns a static example. To do that, Oscar uses Postman. However, Oscar recommends using SoapUI for things that are custom and flexible.

It’s interesting to see the diversity in approaches to API Design.