Stop the bloat: Clarity is Kindness

While reading about Redocly's new document, your MCP server feature, I find myself reflecting on Aaron Francis's phrase "clarity is kindness". While Aaron was pushing for clearer SQL, I've been applying this everywhere lately.

The explosion of AI tools in software has slowly driven me insane; I swear if I have to read one more fully bloated AI-generated issue, spec doc, planning page or API spec, I am going to drive our entire planet into the sun. When documenting, clarity is important, regardless of whether the end user is an AI Agent or a human. Fully generating documents, descriptions, and other forms of communication creates wasted noise and muddies the waters for everyone.

Documentation is there for an intent, not to tick a box.

-- Alexander

The API Roundup

API News, links, and tools from around the web

The New Go JSON API: Twice As Fast, or 1.5x Slower? 

I have been excited about the new Go JSON API for a while now, but maybe I got excited too early... Daniel Lemire puts together benchmarks comparing the old API/old engine, old API/new engine, and the new API/new engine. What's interesting is the new API and engine might not be as fast as we think.

NestJS

NestJS, a popular web framework for Node, dropped a huge update recently. NestJS is now ESM-first, using Rspack instead of Webpack and adding standard schema support. This is one hell of a release, chock-full of goodies, for example, route conflict diagnostics. Their release blog has all the details. Well done to the team.

Restify 12

It's been a long time since I heard anything about Restify. It originally launched as an optimised way to build RESTful Node services. It's been close to three years since their last release, but they're back with version 12, adding Node 26 support and more.

The Consensus API

I love finding an API I didn't know about. The Consensus (a publication on building software) has its own API for reading data with Agents or building notifications against their data. You can get info on job listings, funding, and feeds through the API. It's nicely documented, too.

Who Uses an API

APIs aren't just for developers or Agents anymore. Bruno talks about how consumers are growing beyond developers to people in marketing, education, and beyond. API docs need to feel less technical and explain functionality more clearly. Honestly, this also links back to my intro, Clarity is Kindness.

Fuzzing the State Machines Inside My HTTP Client

A journey of adding property-based testing to ffetch (a TypeScript replacement for fetch with retries and timeout control). An interesting read about how adding property-based testing found ten defects that the author had no reason to suspect. Maybe I need to start doing this for some of my flows.

APIs You Won't Hate

The latest from the team at API's You Won't Hate.

The Podcast

We have three exciting podcasts on the cutting room floor getting ready for release. We love the podcast and would love to involve more of the community. If you're doing something interesting in the API space and want to chat about it, please reach out to us!

From our Community

Articles written and shared in our free Slack community.

Document your MCP server with introspect-mcp

I mentioned this in the intro, but Dmytro shared it in our Slack group. Redocoly takes your MCP server capabilities and documents them in your OpenAPI spec for everyone to read.

Thanks so much to our members: Kin, Juxt, Brandon K, Frank, James D, Bill D. Your support means the world to us!

✌️ Until next time,
Alexander, Phil & Mike