This blog post is part of the APIFutures coordinated by Matthew Reinbold where he recruited some of the best and brightest for their perspectives on APIs in 2024. Hit the end of this article for links to a few other participants and the full list.


For the last year, I’ve enjoyed using ChatGPT and its cousins. At first, it was morbid curiosity to see how badly these AIs saw the world. Then it became a serious “how do these AIs see the world?”

As I went deeper, I was struck by another idea: rubber ducking. I started using generative AI against my own writing to raise counter-points and consider different perspectives. Then I realized code would be more fun.

We’ve all played with code generation using templates, static code analysis, and method finger printing approaches. In ancient times, I even built an “API spider” that would follow links in API payloads to map out APIs. When I did that in my day job, I was fine until I added parameter stuffing to discern the correct parameters and pounded the API senseless. Oops.

But generative AI offers another path. What if I could point AI at my API and have it explore? It turns out through the custom ChatGPT functionalitycalled Generative Pre-trained Transformers or simply GPTs – combined with Actions, you can do mostly that. Specifically, you create a GPT, connect it to your OpenAPI plugin, and use Actions to map the two together. Each of your endpoints becomes a RPC-like function for a quick and easy way to explore an API without much effort.

Which brings us back to the oldest problem in APIs: documentation.

What AI needs for APIs

To use AI to make sense of your API, you need to describe it precisely to give it endpoints, parameters, and authentication schemes.

Unfortunately, the world isn’t as clean and precise as we’d like. Once you step outside the familiar ground of big, name brand APIs, we enter this world where internal APIs drive the vast majority of business. And because they’re internal and long-lived, most don’t have basic documentation, let alone OpenAPI specs so we live in this world of tooling that is so freakin’ close to being useful but is more frustrating than enlightening.

Looking forward with AIs and APIs

In 2024, we’re going to see this dichotomy grow.

Poorly described APIs will struggle for adoption on all fronts. Your docs are going to fall further behind, your SDKs will never fit quite right, your integrations will be fragile, and your Marketing and Sales team will always have an uphill battle. A cool website won’t save you. Another SDK won’t save you. A great devrel team will only delay the inevitable.

Alternatively, the APIs that are well-documented in clear, consistent ways are going to be embedded in more places faster than ever before. When someone goes to ChatGPT – or Copilot or Bard or Grok – and says “build an app that..” it will use tools it can discover, understand, and accomplish those goals. Even more importantly, that person may not even be a developer. A savvy business analyst who previously lived in Excel working their macro wizardry may end up using your API without ever realizing it.

By the way, yes that is the ideal in a “Business Case for Developer Experience” realm.

In short – just like humans – an AI can’t build with what it can’t understand.

For more API Futures Perspectives:

Write a Reply or Comment

Your email address will not be published.