David Biesack (he/him)

"Don't Go Off the Rails" - my latest post on #APIDesignMatters ; I discuss the value of API Governance. https://apidesignmatters.org/2026/05/13/dont-go-off-the-rails

I have completed my migration of #APIDesignMatters off of Substack to my new domain: https://apidesignmatters.org . I've converted to Markdown and have hosted in an open-source GitHub repository at https://github.com/apidesignmatters/apidesignmatters.github.io and released it under the Creative Commons CC BY-NC 4.0 license (Attribution-NonCommercial 4.0 International).

I'll post future content at apidesignmatters.org and share on LinkedIn and here (follow me at @DavidBiesack ) using the hashtag #APIDesignMatters .

I want to give a huge shout out to Juan Cruz Viotti and the #jsonschema tool he released as OSS, https://github.com/sourcemeta/jsonschema .
I recently updated our governance pipeline to use jsonschema to produce better analysis of the examples in our #OpenAPI documents. We created a lint-json-schema-examples tool which maps across all schemas in an OpenAPI doc and uses jsonschema to validate each example. While Spectral does some basic validation of examples, the diagnostics from jsonschema are far superior.

Looks like #venmo services are down. Login fails. "Something went wrong. Try again." error on multiple devices, web, etc. #DownDetector shows:

API Design Matters is Moving!

If you have followed my API Design Matters substack... I'm moving to a new location: https://apidesignmatters.org

See my farewell post on substack: https://open.substack.com/pub/apidesignmatters/p/api-design-matters-is-moving?r=224cwh&utm_campaign=post&utm_medium=web&showWelcomeOnShare=true and follow https://apidesignmatters.org for new #APIDesignMatters content!

The Provenance of #APIDesignMatters. Who inspires you in the #API Space? https://open.substack.com/pub/apidesignmatters/p/provenance?r=224cwh&utm_campaign=post&utm_medium=web&showWelcomeOnShare=true

New post in "API Design Matters": API Design Antipattern: Leaky Abstractions

https://open.substack.com/pub/apidesignmatters/p/api-design-antipattern-leaky-abstractions?r=224cwh&utm_campaign=post&utm_medium=web&showWelcomeOnShare=true

#APIs #APIDesignMatters

I shared an Idea for a new feature in #Spectral - see https://github.com/stoplightio/spectral/discussions/2815, "Validate #OAS specification extensions"

Published today: "The API Team Mantra [200 Is Not OK]" in #APIDesignMatters where I delve into what I shared recently: "The mantra of a good API Program Manager/Product Manager/Developer Advocate: APIs should help you solve your problems. APIs should not be your problem." https://apidesignmatters.substack.com/p/the-api-team-mantra
#API #APIs #APIGovernance #APIProductManagement

Next post in #APIDesignMatters -- continuing my API Design Patterns series: "From Here to There, from Where to Here"
Patterns for Web API Query Parameters", https://apidesignmatters.substack.com/p/from-here-to-there-from-where-to

I had a blast yesterday chatting with Derric Gilling, recording a session for the #Moesif "APIs over IPAs (How to Build an API-first Business)" podcast. I shared a bit of how we built our #API program (and #APIFirst culture) at Apiture.

I'm attending #Leap2025 today - join me and #Tyk today!

I received a 2025 #StrangePlanet page-a-day calendar as a gift... now I'm severely tempted to change my "Thanks!" in email and @Slack responses to "Gratitude!"
https://www.nathanwpyle.art/merchandise

New in "API Design Matters": "Wherefore HATEOAS", my views and commentary on Hypermedia APIs. https://apidesignmatters.substack.com/p/wherefore-hateoas
#APIDesignMatters #APIs #HATEOAS

New article on API Design patterns in #APIDesignMatters: Leave a Calling Card: Make API responses more self-descriptive with reference objects https://open.substack.com/pub/apidesignmatters/p/leave-a-calling-card?r=224cwh&utm_campaign=post&utm_medium=web&showWelcomeOnShare=true

Validating API Requests - API design patterns for assisting clients validate API calls with server-side validation , #APIDesignMatters https://open.substack.com/pub/apidesignmatters/p/validating-api-requests?r=224cwh&utm_campaign=post&utm_medium=web&showWelcomeOnShare=true

#APIDesignMatters has passed 1,000 subscribers! https://open.substack.com/pub/apidesignmatters/p/an-api-design-matters-milestone?r=224cwh&utm_campaign=post&utm_medium=web&showWelcomeOnShare=true

New article in #APIDesignMatters: API Naming Patterns https://open.substack.com/pub/apidesignmatters/p/api-naming-patterns?r=224cwh&utm_campaign=post&utm_medium=web&showWelcomeOnShare=true

Since removing the paid subscriber tier on #APIDesignMatters last month, this archive article is now free for all visitors:
We Talk "API" One Day https://apidesignmatters.substack.com/p/we-talk-api-one-day :
I’m “going meta”. I’m not going to talk about how languages (like the OpenAPI Specification and JSON Schema) describe specific #API concepts and artifacts, but rather how we talk about APIs themselves. In other words, I want to explore the Ubiquitous Language of APIS.

My first post in my API Design Patterns series on API Design Matters: I dissect the use (the good, bad, and ugly) of the CRUD pattern in API design: https://apidesignmatters.substack.com/p/oh-crud #APIDesignMatters #API

The Art of #API Design, my latest post in #APIDesignMatters: https://apidesignmatters.substack.com/p/the-art-of-api-design

In #APIDesignMatters, I say "Pet Store: Just Say No!" and introduce two new contenders to replace Pet Store as the canonical #API definition "example" for #OpenAPI. https://apidesignmatters.substack.com/p/pet-store-api-just-say-no

"The API Design Mind Game" --
When it comes to API puzzles, it's all in your head. My latest #APIDesignMatters post, https://apidesignmatters.substack.com/p/the-api-design-mind-game

Please read and share my next "API Design Matters" post: "Improve the Security of Your API's Data"
https://open.substack.com/pub/apidesignmatters/p/improve-the-security-of-your-apis?r=224cwh&utm_campaign=post&utm_medium=web&showWelcomeOnShare=true
#API #APIDesignMatters #TheLanguageOfAPIs

Had a blast chatting with @rjrodger this week, recording an upcoming #Voxgig "Fireside chat" on building a robust #APIFirst API program, Developer Relations, #DX, #APIDesign and more. Look for it coming in a few weeks; until then, check out the Voxgig archives! https://www.voxgig.com/podcast

For my #APIDesignMatters substack paid subscribers, "We Talk API One Day", https://open.substack.com/pub/apidesignmatters/p/we-talk-api-one-day?r=224cwh&utm_campaign=post&utm_medium=web&showWelcome=true , ("The Ubiquitous Language of #APIs")

Thank You Erik Wilde for having me back on your "Getting APIs to Work" Youtube channel and for highlighting my "API Design Matters" substack and my "Language of APIs" series. Next up is JSON Schema - the Language of API Data https://www.linkedin.com/feed/update/urn:li:activity:7135885308293746688/ and https://www.youtube.com/watch?v=s9kVJvyBKjs
#APIDesignMatters #TheLanguageOfAPIs #APIs

Today, I begin a deeper dive into expressing API Security with OpenAPI, by exploring the notation of security schemes and security requirement objects, with some commentary on the tradeoffs between conciseness vs. consistency, and what can and cannot be expressed with OpenAPI when it comes to keeping your API secure. #TheLanguageOfAPIs #OpenAPI #APIs #APIDesignMatters https://open.substack.com/pub/apidesignmatters/p/understanding-the-language-of-api?r=224cwh&utm_campaign=post&utm_medium=web

I finished re-reading The Wheel of Time #TWOT series by Robert Jordan/Brandon Sanderson this weekend (it's been over a decade since I last read them). 14 books, 12,000 pages. It took a while. But I was stunned (again) at how good the last three books really are. The entire series sets up an strong expectation of how you deeply want it to end... then a 200 page chapter "The Last Battle" makes you glad it is not what you expected.

Some tips on update operations for #APIs : "Keep Me Updated, OK?", part of the #LanguageOfAPIDesign and #APIDesignMatters
https://apidesignmatters.substack.com/p/keep-me-updated-ok

Check out SmartBear's YouTube series on the new 2023 #OWASPTop10 for Secure #APIs: https://www.youtube.com/watch?v=nIWBp_nvzq4&list=PLrA5ciulugn8nydmfvt9cGBgDFqg8XbEt

I just typed `rags:` instead of `tags:` in an #OpenAPI document. #NotTheFirstTime

Thanks to Erik Wilde for letting me join him on his Getting APIs to Work YouTube channel. I hope you enjoy it and will continue the conversation! #LanguageOfAPIDesign #APIDesignMatters #APIs https://www.linkedin.com/feed/update/urn:li:activity:7102266311681916928/

"Getting Creative with OpenAPI" -- my next article in the #LanguageOfAPIDesign series in #APIDesignMatters, where I walk through many aspects of defining a resource creation operation in #OpenAPI https://apidesignmatters.substack.com/p/getting-creative-with-openapi #APIs

@jaapio I also hope the #workflows project at #OAI will also lead to its adoption as a standard for documenting API flows (sequences of chained API calls) that demonstrate higher level business cases solved with #APIs https://github.com/OAI/sig-workflows/blob/main/versions/1.0.0.md

#IWonder: what percent of the worldwide Cloud storage is now simply email blocked sender lists?

Today, I present Part II of the Master JSON Schema's Subtleties article, imaginatively titled Master More JSON Schema’s Subtleties. Part of the #LanguageOfAPIDesign and #APIDesignMatters . Explore more use of unevaluatedProperties, JSON Merge Patch, and more. #APIs

https://apidesignmatters.substack.com/p/master-more-json-schemas-subtleties

Catch me on Erik Wilde's "Getting #APIs to Work" YouTube Channel: https://www.youtube.com/watch?v=J3-0P4kt9rg
(and LinkedIn Post https://www.linkedin.com/feed/update/urn:li:activity:7089489531409707008/ ) Subscribe to #APIDesignMatters at https://apidesignmatters.substack.com/

@matthew @mamund also touched on this point in #Stoplight 's #APIIntersection podcast - i.e. companies that have been making /selling widgets for 100+ years but are now embracing tech to do the job better. https://youtu.be/qlhJp_yUTLg?list=PLFLmRVQdyTF1D5aVoXuq4YP_MQawMMTbC&t=2109

@cwoodruff Citing #Emacs might start editor wars, so I'll instead just say #VSCode and #markdownlint extension and VS Code Preview.

Next up on #APIDesignMatters: Master JSON Schema's Subtleties: a post on the more subtle nuances of #JSONSchema as a language for designing #API data. Knowing these details will help you understand other APIs’ schemas and help you construct your own.

https://apidesignmatters.substack.com/p/master-json-schemas-subtleties

Enjoy, and please subscribe and share!

Woot - The cool folks at #Stoplight invited me to their #API Intersections podcast, and it dropped today. We talked about API [First] Design, my #APIDesignMatters substack https://apidesignmatters.substack.com/ and more.
Thanks for the opportunity Jason Harmon and team!

Blog - https://bit.ly/djb-stoplight-blog-2023-07

Podcast - https://bit.ly/djb-stoplight-podcast-2023-07

Attend #apidays and you can watch a talk by José Haro Peralta on #API Design Modeling https://www.linkedin.com/posts/jose-haro-peralta_apis-apidesign-domaindrivendesign-ugcPost-7079521597396590592-9l0m?utm_source=share&utm_medium=member_desktop (which is quite a bit like my #APIDesignMatters work)

#SmartBear announces OpenAPI 3.1 support for their #OSS #API tools: https://smartbear.com/news/news-releases/swagger-open-source-tooling-now-supports-latest-op/ Get them here: https://swagger.io/tools/open-source/

Next up in #APIDesignMatters: Learning the Language of API Data: On the road to becoming fluent with JSON Schema
#JSONSchema
https://apidesignmatters.substack.com/p/learning-the-language-of-api-data